@martinffx/atelier 1.0.2 → 1.1.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/CHANGELOG.md +9 -0
- package/README.md +1 -5
- package/package.json +1 -1
- package/skills/{code-conventional-commit → code-commit}/SKILL.md +16 -1
- package/skills/code-commit/references/pr-workflow.md +145 -0
- package/skills/code-debug/SKILL.md +0 -4
- package/skills/code-review/references/reviewers.md +3 -11
- package/skills/code-review/references/rq.md +4 -5
- package/skills/oracle-grillme/SKILL.md +160 -0
- package/skills/oracle-grillme/references/ADR-FORMAT.md +47 -0
- package/skills/oracle-grillme/references/CONTEXT-FORMAT.md +63 -0
- package/skills/spec-finish/SKILL.md +2 -5
- package/skills/spec-implement/SKILL.md +1 -1
- package/skills/code-conventional-commit/evals/evals.json +0 -23
- package/skills/code-conventional-commit/workspace/iteration-1/eval-0/with_skill/outputs/commit-message.txt +0 -4
- package/skills/code-conventional-commit/workspace/iteration-1/eval-0/with_skill/outputs/eval_metadata.json +0 -6
- package/skills/code-conventional-commit/workspace/iteration-1/eval-1/with_skill/outputs/eval_metadata.json +0 -6
- package/skills/code-conventional-commit/workspace/iteration-1/eval-1/with_skill/outputs/validation-result.txt +0 -16
- package/skills/code-conventional-commit/workspace/iteration-1/eval-2/with_skill/outputs/commit-message.txt +0 -8
- package/skills/code-conventional-commit/workspace/iteration-1/eval-2/with_skill/outputs/eval_metadata.json +0 -6
- package/skills/code-conventional-commit/workspace/iteration-1/report.html +0 -1325
- package/skills/code-git-worktrees/SKILL.md +0 -218
- package/skills/code-perf/SKILL.md +0 -163
- package/skills/code-perf/references/common-bottlenecks.md +0 -124
- package/skills/code-perf/references/optimization-patterns.md +0 -167
- package/skills/code-perf/references/profiling-tools.md +0 -126
- package/skills/code-security/SKILL.md +0 -183
- package/skills/code-security/references/owasp-top-10.md +0 -129
- package/skills/code-security/references/security-tools.md +0 -102
- package/skills/code-security/references/vulnerability-patterns.md +0 -129
- package/skills/code-stacked-commit/SKILL.md +0 -155
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,14 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [1.1.0](https://github.com/martinffx/atelier/compare/v1.0.2...v1.1.0) (2026-05-23)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### Features
|
|
7
|
+
|
|
8
|
+
* **skills:** add oracle-grillme socratic interrogation skill ([6ad5ce5](https://github.com/martinffx/atelier/commit/6ad5ce52428863b51fec83880ce8083bb80aa3a0))
|
|
9
|
+
* **skills:** add oracle-grillme socratic interrogation skill ([fd21606](https://github.com/martinffx/atelier/commit/fd2160639b82ba335963bec3128d9c6a5b5801b6))
|
|
10
|
+
* **skills:** add PR creation workflow to code-commit ([25bb826](https://github.com/martinffx/atelier/commit/25bb8264364cb1c5ee843baea0127eaba3935c78))
|
|
11
|
+
|
|
3
12
|
## [1.0.2](https://github.com/martinffx/atelier/compare/v1.0.1...v1.0.2) (2026-05-23)
|
|
4
13
|
|
|
5
14
|
|
package/README.md
CHANGED
|
@@ -29,7 +29,7 @@ That's it. Your project is now configured for spec-driven development.
|
|
|
29
29
|
|
|
30
30
|
Atelier sets up three things in your project:
|
|
31
31
|
|
|
32
|
-
### 1. Skills (
|
|
32
|
+
### 1. Skills (30 available)
|
|
33
33
|
|
|
34
34
|
Specialized knowledge modules that auto-invoke based on context. Install them via the CLI (`--all` flag) or separately:
|
|
35
35
|
|
|
@@ -194,10 +194,6 @@ Task-specific tools you invoke when you need them.
|
|
|
194
194
|
- `code-review` — Multi-agent code review with specialized reviewers
|
|
195
195
|
- `code-debug` — Systematic debugging workflow
|
|
196
196
|
- `code-docs` — README, API docs, changelog generation
|
|
197
|
-
- `code-security` — Security audit and vulnerability detection
|
|
198
|
-
- `code-perf` — Performance profiling and optimization
|
|
199
|
-
- `code-git-worktrees` — Isolated git worktrees for feature work
|
|
200
|
-
- `code-stacked-commit` — Manage stacked commits with Graphite
|
|
201
197
|
- `code-subagents` — Dispatch patterns for parallel implementation
|
|
202
198
|
|
|
203
199
|
Skills are auto-invoked based on their description when you work with relevant technologies. No commands needed—just install and AI agents will use them when appropriate.
|
package/package.json
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
name: code-
|
|
2
|
+
name: code-commit
|
|
3
3
|
description: Generate and validate conventional commit messages following the conventionalcommits.org spec. Use whenever the user wants to commit code, mentions commit messages, git commit, or asks to create a commit. Triggers on "commit", "git commit", "conventional", or when reviewing commit message format.
|
|
4
4
|
user-invocable: true
|
|
5
5
|
---
|
|
@@ -76,6 +76,21 @@ When user asks to validate or check a commit message:
|
|
|
76
76
|
4. Check subject follows rules (lowercase, imperative, no period)
|
|
77
77
|
5. Flag any issues found
|
|
78
78
|
|
|
79
|
+
### 3. Create Pull Request
|
|
80
|
+
|
|
81
|
+
When user wants to open a PR or after finishing commits on a feature branch:
|
|
82
|
+
|
|
83
|
+
1. Verify on a feature branch (not main): `git branch --show-current`
|
|
84
|
+
2. Check for project PR template: `ls .github/PULL_REQUEST_TEMPLATE.md`
|
|
85
|
+
3. Push branch if needed: `git push -u origin <branch>`
|
|
86
|
+
4. Create PR via `gh pr create`:
|
|
87
|
+
- Use `--fill` if commits are clean (auto-populates title/body)
|
|
88
|
+
- Use `--draft` for work-in-progress
|
|
89
|
+
- Use interactive mode if body needs custom content
|
|
90
|
+
5. Show the PR URL to the user
|
|
91
|
+
|
|
92
|
+
See [references/pr-workflow.md](references/pr-workflow.md) for full workflow details.
|
|
93
|
+
|
|
79
94
|
## Input Methods
|
|
80
95
|
|
|
81
96
|
| Input | Action |
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
# Pull Request Workflow
|
|
2
|
+
|
|
3
|
+
Creating GitHub pull requests via the `gh` CLI.
|
|
4
|
+
|
|
5
|
+
## Prerequisites
|
|
6
|
+
|
|
7
|
+
- `gh` CLI installed and authenticated: `gh auth status`
|
|
8
|
+
- Remote `origin` points to GitHub: `git remote -v`
|
|
9
|
+
- On a feature branch (not main): `git branch --show-current`
|
|
10
|
+
|
|
11
|
+
## Check for Project Template
|
|
12
|
+
|
|
13
|
+
Before creating a PR, check if the project has its own PR template:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
# Check for PR template in .github/
|
|
17
|
+
ls .github/PULL_REQUEST_TEMPLATE.md 2>/dev/null || echo "No project template found"
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
**If found:** Use it. The `gh pr create` command will automatically pick it up.
|
|
21
|
+
|
|
22
|
+
**If not found:** Use the minimal template below.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## Create Pull Request
|
|
27
|
+
|
|
28
|
+
### Option 1: Auto-fill from commits (recommended)
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
gh pr create --fill
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
This uses the commit messages as the PR title and body. Best when commits are clean and conventional.
|
|
35
|
+
|
|
36
|
+
### Option 2: Interactive
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
gh pr create
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Opens an editor with the template. Fill in title and body interactively.
|
|
43
|
+
|
|
44
|
+
### Option 3: Inline (for simple PRs)
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
gh pr create --title "feat(auth): add JWT authentication" --body "Implements token-based auth with refresh support."
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## PR Title Format
|
|
53
|
+
|
|
54
|
+
Follow conventional commit style for PR titles:
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
<type>(<scope>): <description>
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Examples:
|
|
61
|
+
- `feat(api): add user profile endpoint`
|
|
62
|
+
- `fix(db): resolve connection pool leak`
|
|
63
|
+
- `docs(readme): update installation instructions`
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## PR Body Template (fallback if no project template)
|
|
68
|
+
|
|
69
|
+
```markdown
|
|
70
|
+
## Description
|
|
71
|
+
<!-- What does this PR do? -->
|
|
72
|
+
|
|
73
|
+
## Changes
|
|
74
|
+
<!-- What changed? -->
|
|
75
|
+
|
|
76
|
+
## Testing
|
|
77
|
+
<!-- How was this tested? -->
|
|
78
|
+
|
|
79
|
+
## Checklist
|
|
80
|
+
- [ ] Tests pass
|
|
81
|
+
- [ ] Commits follow conventional format
|
|
82
|
+
- [ ] Documentation updated (if needed)
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## Linking Issues
|
|
88
|
+
|
|
89
|
+
Add issue references in the PR body:
|
|
90
|
+
|
|
91
|
+
```markdown
|
|
92
|
+
Closes #123
|
|
93
|
+
Fixes #456
|
|
94
|
+
Relates to #789
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
This auto-closes linked issues when the PR merges.
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## Draft PRs
|
|
102
|
+
|
|
103
|
+
For work-in-progress PRs:
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
gh pr create --draft
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Mark as ready later:
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
gh pr ready <pr-number>
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## Review Requests
|
|
118
|
+
|
|
119
|
+
Request reviewers after creating the PR:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
gh pr edit <pr-number> --add-reviewer username
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Or add via the GitHub web UI.
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## Verify PR Created
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
gh pr view --web # Open in browser
|
|
133
|
+
gh pr status # Show PR status
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## Common Mistakes
|
|
139
|
+
|
|
140
|
+
| Mistake | Fix |
|
|
141
|
+
|---------|-----|
|
|
142
|
+
| PR from main branch | Switch to feature branch first |
|
|
143
|
+
| No remote | `git remote add origin <url>` |
|
|
144
|
+
| Unpushed commits | `git push -u origin <branch>` |
|
|
145
|
+
| PR body is empty | Use `--fill` or write a description |
|
|
@@ -240,16 +240,12 @@ const name = user.profile.name;
|
|
|
240
240
|
2. Identify hot paths
|
|
241
241
|
3. Optimize the bottleneck
|
|
242
242
|
|
|
243
|
-
**See code-perf skill for detailed performance debugging.**
|
|
244
|
-
|
|
245
243
|
---
|
|
246
244
|
|
|
247
245
|
## Skill Loading
|
|
248
246
|
|
|
249
247
|
Check available skills for additional debugging support:
|
|
250
248
|
|
|
251
|
-
- If dealing with performance issues → load code-perf
|
|
252
|
-
- If security vulnerability suspected → load code-security
|
|
253
249
|
- If debugging tests → load oracle-testing
|
|
254
250
|
|
|
255
251
|
---
|
|
@@ -97,8 +97,6 @@ Output findings in this format:
|
|
|
97
97
|
- **Pre-existing**: Yes/No (check if existed before this PR)
|
|
98
98
|
```
|
|
99
99
|
|
|
100
|
-
Loads: `code-security` (if exists)
|
|
101
|
-
|
|
102
100
|
---
|
|
103
101
|
|
|
104
102
|
### Performance Reviewer
|
|
@@ -128,8 +126,6 @@ Output findings in this format:
|
|
|
128
126
|
- **Pre-existing**: Yes/No
|
|
129
127
|
```
|
|
130
128
|
|
|
131
|
-
Loads: `code-perf` (if exists)
|
|
132
|
-
|
|
133
129
|
---
|
|
134
130
|
|
|
135
131
|
### Correctness Reviewer
|
|
@@ -532,8 +528,6 @@ Each reviewer should load relevant skills before reviewing:
|
|
|
532
528
|
|
|
533
529
|
| Reviewer Type | Skills to Load |
|
|
534
530
|
|---------------|----------------|
|
|
535
|
-
| Security | `code-security` |
|
|
536
|
-
| Performance | `code-perf` |
|
|
537
531
|
| Correctness | Language-specific (`typescript-testing`, `python-testing`, etc.) |
|
|
538
532
|
| Maintainability | Testing skills |
|
|
539
533
|
| Architecture | `oracle-architect` |
|
|
@@ -580,10 +574,9 @@ prompt: |
|
|
|
580
574
|
|
|
581
575
|
YOUR FIRST TASK - LOAD SKILLS:
|
|
582
576
|
As a Security Reviewer, you should load relevant skills before reviewing:
|
|
583
|
-
1. Load `skill:
|
|
584
|
-
2. Load `skill: typescript-testing` (if available) - Use the `skill` tool
|
|
577
|
+
1. Load `skill: typescript-testing` (if available) - Use the `skill` tool
|
|
585
578
|
|
|
586
|
-
|
|
579
|
+
This skill contains TypeScript testing guidance that will help you identify issues.
|
|
587
580
|
|
|
588
581
|
Focus areas after loading skills:
|
|
589
582
|
- Authentication and authorization flaws
|
|
@@ -663,8 +656,7 @@ prompt: |
|
|
|
663
656
|
|
|
664
657
|
YOUR FIRST TASK - LOAD SKILLS:
|
|
665
658
|
As a PerformanceOperator Reviewer, you should load relevant skills before reviewing:
|
|
666
|
-
1. Load `skill:
|
|
667
|
-
2. Load `skill: typescript-testing` (if available) - Use the `skill` tool
|
|
659
|
+
1. Load `skill: typescript-testing` (if available) - Use the `skill` tool
|
|
668
660
|
|
|
669
661
|
Focus areas after loading skills:
|
|
670
662
|
- Performance issues that matter in prod
|
|
@@ -62,8 +62,7 @@ prompt: |
|
|
|
62
62
|
4. **Identify skills to load** based on detected language/framework:
|
|
63
63
|
- TypeScript → typescript-testing, typescript-fastify (if fastify framework)
|
|
64
64
|
- Python → python-testing, python-fastapi (if fastapi framework)
|
|
65
|
-
|
|
66
|
-
- Performance concerns → code-perf
|
|
65
|
+
|
|
67
66
|
|
|
68
67
|
Return ONLY valid JSON (no markdown, no code blocks):
|
|
69
68
|
{
|
|
@@ -73,7 +72,7 @@ prompt: |
|
|
|
73
72
|
"domain": "web-api|frontend|database|..."
|
|
74
73
|
},
|
|
75
74
|
"reviewers": ["Security", "Correctness"],
|
|
76
|
-
"skills_to_load": ["typescript-testing"
|
|
75
|
+
"skills_to_load": ["typescript-testing"]
|
|
77
76
|
}
|
|
78
77
|
```
|
|
79
78
|
|
|
@@ -83,7 +82,7 @@ prompt: |
|
|
|
83
82
|
{
|
|
84
83
|
"context": { "language": "typescript", "framework": "fastify", "domain": "web-api" },
|
|
85
84
|
"reviewers": ["Security", "Correctness", "PerformanceOperator"],
|
|
86
|
-
"skills_to_load": ["typescript-testing"
|
|
85
|
+
"skills_to_load": ["typescript-testing"]
|
|
87
86
|
}
|
|
88
87
|
```
|
|
89
88
|
|
|
@@ -102,7 +101,7 @@ prompt: |
|
|
|
102
101
|
Before dispatching reviewers, the detected skills are passed to each reviewer:
|
|
103
102
|
```json
|
|
104
103
|
{
|
|
105
|
-
"skills_to_load": ["typescript-testing"
|
|
104
|
+
"skills_to_load": ["typescript-testing"]
|
|
106
105
|
}
|
|
107
106
|
```
|
|
108
107
|
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: oracle-grillme
|
|
3
|
+
description: >
|
|
4
|
+
Socratic interrogation of plans against the project's domain model and documented decisions.
|
|
5
|
+
Use when the user wants to stress-test a plan, clarify terminology, or validate assumptions
|
|
6
|
+
against existing domain language. Updates CONTEXT.md and ADRs inline as decisions crystallise.
|
|
7
|
+
user-invocable: true
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Grill Me
|
|
11
|
+
|
|
12
|
+
Relentless questioning of your plan against the project's domain model, sharpening terminology and updating documentation (CONTEXT.md, ADRs) inline as decisions crystallise.
|
|
13
|
+
|
|
14
|
+
## When to Use
|
|
15
|
+
|
|
16
|
+
- **Stress-testing a plan** — "I want to add a refund flow to the Order service"
|
|
17
|
+
- **Clarifying fuzzy language** — "We're calling it 'account' but is that a Customer or a User?"
|
|
18
|
+
- **Onboarding to a domain** — "Walk me through how the Billing context relates to Ordering"
|
|
19
|
+
- **Before writing specs** — Ensuring the domain language is solid before `spec-research` begins
|
|
20
|
+
- **After code review** — "The PR introduces 'cancellation' but our glossary says..."
|
|
21
|
+
|
|
22
|
+
## When NOT to Use
|
|
23
|
+
|
|
24
|
+
- **Simple implementation questions** — Use `oracle-challenge` or `oracle-architect` instead
|
|
25
|
+
- **Debugging** — Use `code-debug`
|
|
26
|
+
- **Testing strategy** — Use `oracle-testing`
|
|
27
|
+
- **Already in spec workflow** — Use `spec-research` + `oracle-architect` for domain discovery during the spec process
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## How It Works
|
|
32
|
+
|
|
33
|
+
<interview-loop>
|
|
34
|
+
|
|
35
|
+
Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
|
|
36
|
+
|
|
37
|
+
Ask the questions one at a time, waiting for feedback on each question before continuing.
|
|
38
|
+
|
|
39
|
+
If a question can be answered by exploring the codebase, explore the codebase instead.
|
|
40
|
+
|
|
41
|
+
</interview-loop>
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## Domain Awareness
|
|
46
|
+
|
|
47
|
+
### Discovering Context
|
|
48
|
+
|
|
49
|
+
Most repos have a single context:
|
|
50
|
+
|
|
51
|
+
```
|
|
52
|
+
/
|
|
53
|
+
├── CONTEXT.md
|
|
54
|
+
├── docs/
|
|
55
|
+
│ └── adr/
|
|
56
|
+
│ ├── 0001-event-sourced-orders.md
|
|
57
|
+
│ └── 0002-postgres-for-write-model.md
|
|
58
|
+
└── src/
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
/
|
|
65
|
+
├── CONTEXT-MAP.md
|
|
66
|
+
├── docs/
|
|
67
|
+
│ └── adr/ ← system-wide decisions
|
|
68
|
+
├── src/
|
|
69
|
+
│ ├── ordering/
|
|
70
|
+
│ │ ├── CONTEXT.md
|
|
71
|
+
│ │ └── docs/adr/ ← context-specific decisions
|
|
72
|
+
│ └── billing/
|
|
73
|
+
│ ├── CONTEXT.md
|
|
74
|
+
│ └── docs/adr/
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
|
|
78
|
+
|
|
79
|
+
### During the Session
|
|
80
|
+
|
|
81
|
+
#### Challenge Against the Glossary
|
|
82
|
+
|
|
83
|
+
When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately.
|
|
84
|
+
|
|
85
|
+
> "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
|
|
86
|
+
|
|
87
|
+
#### Sharpen Fuzzy Language
|
|
88
|
+
|
|
89
|
+
When the user uses vague or overloaded terms, propose a precise canonical term.
|
|
90
|
+
|
|
91
|
+
> "You're saying 'account' — do you mean the Customer or the User? Those are different things."
|
|
92
|
+
|
|
93
|
+
#### Discuss Concrete Scenarios
|
|
94
|
+
|
|
95
|
+
When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
|
|
96
|
+
|
|
97
|
+
#### Cross-Reference With Code
|
|
98
|
+
|
|
99
|
+
When the user states how something works, check whether the code agrees. If you find a contradiction, surface it:
|
|
100
|
+
|
|
101
|
+
> "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
|
|
102
|
+
|
|
103
|
+
#### Update CONTEXT.md Inline
|
|
104
|
+
|
|
105
|
+
When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [references/CONTEXT-FORMAT.md](./references/CONTEXT-FORMAT.md).
|
|
106
|
+
|
|
107
|
+
`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
|
|
108
|
+
|
|
109
|
+
#### Offer ADRs Sparingly
|
|
110
|
+
|
|
111
|
+
Only offer to create an ADR when all three are true:
|
|
112
|
+
|
|
113
|
+
1. **Hard to reverse** — the cost of changing your mind later is meaningful
|
|
114
|
+
2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
|
|
115
|
+
3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
|
|
116
|
+
|
|
117
|
+
If any of the three is missing, skip the ADR. Use the format in [references/ADR-FORMAT.md](./references/ADR-FORMAT.md).
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## Usage Examples
|
|
122
|
+
|
|
123
|
+
### Stress-Test a New Feature
|
|
124
|
+
```
|
|
125
|
+
/grillme "I want to add a refund flow to the Order service"
|
|
126
|
+
```
|
|
127
|
+
> "Before we go further — your glossary defines 'Order' as a completed purchase. A refund implies the Order is no longer complete. Is 'refund' a state on Order, or a new concept entirely?"
|
|
128
|
+
|
|
129
|
+
### Clarify Ambiguous Terms
|
|
130
|
+
```
|
|
131
|
+
/grillme "We need to handle 'account' deletions"
|
|
132
|
+
```
|
|
133
|
+
> "You said 'account' — your CONTEXT.md has both Customer and User. Which one are we deleting, and what happens to their Orders?"
|
|
134
|
+
|
|
135
|
+
### Validate Against Existing Decisions
|
|
136
|
+
```
|
|
137
|
+
/grillme "I'm switching the write model from Postgres to DynamoDB"
|
|
138
|
+
```
|
|
139
|
+
> "ADR-0002 says we chose Postgres for the write model because of ACID requirements. Have those requirements changed, or is this a new trade-off?"
|
|
140
|
+
|
|
141
|
+
### Onboard to a Domain
|
|
142
|
+
```
|
|
143
|
+
/grillme "Explain how Billing relates to Ordering"
|
|
144
|
+
```
|
|
145
|
+
> "Ordering emits OrderPlaced events. Billing consumes them to create Invoices. But your CONTEXT.md says Invoice is a request for payment — who decides when payment is actually processed?"
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
## Relationship to Other Skills
|
|
150
|
+
|
|
151
|
+
| Skill | Use When |
|
|
152
|
+
|-------|----------|
|
|
153
|
+
| **oracle-grillme** | Questioning domain assumptions, sharpening terminology, updating docs inline |
|
|
154
|
+
| **oracle-challenge** | Critically evaluating a technical approach or decision |
|
|
155
|
+
| **oracle-architect** | Designing components, data models, API contracts during spec-research |
|
|
156
|
+
| **spec-research** | Structured discovery + architecture → spec.md (use grillme before this to solidify language) |
|
|
157
|
+
|
|
158
|
+
**Key distinction:**
|
|
159
|
+
- `oracle-challenge` = "Is this approach valid?" (critical evaluation)
|
|
160
|
+
- `oracle-grillme` = "What do we mean by these words?" (domain interrogation)
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# ADR Format
|
|
2
|
+
|
|
3
|
+
ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
|
|
4
|
+
|
|
5
|
+
Create the `docs/adr/` directory lazily — only when the first ADR is needed.
|
|
6
|
+
|
|
7
|
+
## Template
|
|
8
|
+
|
|
9
|
+
```md
|
|
10
|
+
# {Short title of the decision}
|
|
11
|
+
|
|
12
|
+
{1-3 sentences: what's the context, what did we decide, and why.}
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
|
|
16
|
+
|
|
17
|
+
## Optional Sections
|
|
18
|
+
|
|
19
|
+
Only include these when they add genuine value. Most ADRs won't need them.
|
|
20
|
+
|
|
21
|
+
- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
|
|
22
|
+
- **Considered Options** — only when the rejected alternatives are worth remembering
|
|
23
|
+
- **Consequences** — only when non-obvious downstream effects need to be called out
|
|
24
|
+
|
|
25
|
+
## Numbering
|
|
26
|
+
|
|
27
|
+
Scan `docs/adr/` for the highest existing number and increment by one.
|
|
28
|
+
|
|
29
|
+
## When to Offer an ADR
|
|
30
|
+
|
|
31
|
+
All three of these must be true:
|
|
32
|
+
|
|
33
|
+
1. **Hard to reverse** — the cost of changing your mind later is meaningful
|
|
34
|
+
2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
|
|
35
|
+
3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
|
|
36
|
+
|
|
37
|
+
If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
|
|
38
|
+
|
|
39
|
+
### What Qualifies
|
|
40
|
+
|
|
41
|
+
- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
|
|
42
|
+
- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
|
|
43
|
+
- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
|
|
44
|
+
- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
|
|
45
|
+
- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
|
|
46
|
+
- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
|
|
47
|
+
- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# CONTEXT.md Format
|
|
2
|
+
|
|
3
|
+
## Structure
|
|
4
|
+
|
|
5
|
+
```md
|
|
6
|
+
# {Context Name}
|
|
7
|
+
|
|
8
|
+
{One or two sentence description of what this context is and why it exists.}
|
|
9
|
+
|
|
10
|
+
## Language
|
|
11
|
+
|
|
12
|
+
**Order**:
|
|
13
|
+
{A one or two sentence description of the term}
|
|
14
|
+
_Avoid_: Purchase, transaction
|
|
15
|
+
|
|
16
|
+
**Invoice**:
|
|
17
|
+
A request for payment sent to a customer after delivery.
|
|
18
|
+
_Avoid_: Bill, payment request
|
|
19
|
+
|
|
20
|
+
**Customer**:
|
|
21
|
+
A person or organization that places orders.
|
|
22
|
+
_Avoid_: Client, buyer, account
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Rules
|
|
26
|
+
|
|
27
|
+
- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
|
|
28
|
+
- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a clear resolution.
|
|
29
|
+
- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
|
|
30
|
+
- **Show relationships.** Use bold term names and express cardinality where obvious.
|
|
31
|
+
- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
|
|
32
|
+
- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
|
|
33
|
+
- **Write an example dialogue.** A conversation between a dev and a domain expert that demonstrates how the terms interact naturally and clarifies boundaries between related concepts.
|
|
34
|
+
|
|
35
|
+
## Single vs Multi-Context Repos
|
|
36
|
+
|
|
37
|
+
**Single context (most repos):** One `CONTEXT.md` at the repo root.
|
|
38
|
+
|
|
39
|
+
**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
|
|
40
|
+
|
|
41
|
+
```md
|
|
42
|
+
# Context Map
|
|
43
|
+
|
|
44
|
+
## Contexts
|
|
45
|
+
|
|
46
|
+
- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
|
|
47
|
+
- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
|
|
48
|
+
- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
|
|
49
|
+
|
|
50
|
+
## Relationships
|
|
51
|
+
|
|
52
|
+
- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
|
|
53
|
+
- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
|
|
54
|
+
- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
The skill infers which structure applies:
|
|
58
|
+
|
|
59
|
+
- If `CONTEXT-MAP.md` exists, read it to find contexts
|
|
60
|
+
- If only a root `CONTEXT.md` exists, single context
|
|
61
|
+
- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
|
|
62
|
+
|
|
63
|
+
When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.
|
|
@@ -84,12 +84,10 @@ Use the Skill tool to invoke code-review skill for comprehensive code review.
|
|
|
84
84
|
|
|
85
85
|
## Step 3: Stack Commits
|
|
86
86
|
|
|
87
|
-
Use the Skill tool to invoke code-stacked-commit skill.
|
|
88
|
-
|
|
89
87
|
### Workflow
|
|
90
|
-
1. Review current
|
|
88
|
+
1. Review current commits: `git log --oneline`
|
|
91
89
|
2. Ensure commits are organized logically
|
|
92
|
-
3.
|
|
90
|
+
3. Rebase if needed: `git rebase -i <base-branch>`
|
|
93
91
|
4. Ensure each commit is clean and functional
|
|
94
92
|
|
|
95
93
|
### Commit Guidelines
|
|
@@ -147,7 +145,6 @@ Optional - use code-docs skill if needed.
|
|
|
147
145
|
This skill orchestrates other skills:
|
|
148
146
|
|
|
149
147
|
- Invokes code-review for quality check
|
|
150
|
-
- Invokes code-stacked-commit for commit management
|
|
151
148
|
- Invokes code-docs if documentation needs updates
|
|
152
149
|
|
|
153
150
|
---
|
|
@@ -117,7 +117,7 @@ criteria before writing implementation.
|
|
|
117
117
|
3. Run them — verify they fail for the RIGHT reason
|
|
118
118
|
4. Implement minimal code to make tests pass
|
|
119
119
|
5. Refactor if needed (tests stay green)
|
|
120
|
-
6. Commit (use code-
|
|
120
|
+
6. Commit (use code-commit for commit message)
|
|
121
121
|
```
|
|
122
122
|
|
|
123
123
|
Do NOT write implementation before tests. Do NOT skip "verify it fails." Do NOT write
|
|
@@ -1,23 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"skill_name": "conventional-commit",
|
|
3
|
-
"evals": [
|
|
4
|
-
{
|
|
5
|
-
"id": 1,
|
|
6
|
-
"prompt": "Generate a commit message for these changes: Added a new user profile page component that displays user name, email, and avatar. Also added a settings modal for updating preferences.",
|
|
7
|
-
"expected_output": "Should produce a feat commit with proper scope, imperative subject, and optional body",
|
|
8
|
-
"files": []
|
|
9
|
-
},
|
|
10
|
-
{
|
|
11
|
-
"id": 2,
|
|
12
|
-
"prompt": "Validate this commit message: 'feat: added new login page' - is it valid conventional commit format?",
|
|
13
|
-
"expected_output": "Should identify issues: subject should be lowercase, imperative (add not added), possibly missing scope",
|
|
14
|
-
"files": []
|
|
15
|
-
},
|
|
16
|
-
{
|
|
17
|
-
"id": 3,
|
|
18
|
-
"prompt": "I made breaking changes to the API - the old /v1/users endpoint now returns different JSON structure. Create a commit message that properly indicates this is a breaking change.",
|
|
19
|
-
"expected_output": "Should produce a commit with ! in type (e.g., feat! or fix!) and BREAKING CHANGE footer",
|
|
20
|
-
"files": []
|
|
21
|
-
}
|
|
22
|
-
]
|
|
23
|
-
}
|
|
@@ -1,6 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"eval_id": 0,
|
|
3
|
-
"eval_name": "generate-commit",
|
|
4
|
-
"prompt": "Generate a commit message for these changes: Added a new user profile page component that displays user name, email, and avatar. Also added a settings modal for updating preferences.",
|
|
5
|
-
"assertions": []
|
|
6
|
-
}
|