@martinffx/atelier 1.0.1 → 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.
Files changed (31) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/README.md +1 -5
  3. package/package.json +1 -2
  4. package/skills/{code-conventional-commit → code-commit}/SKILL.md +16 -1
  5. package/skills/code-commit/references/pr-workflow.md +145 -0
  6. package/skills/code-debug/SKILL.md +0 -4
  7. package/skills/code-review/references/reviewers.md +3 -11
  8. package/skills/code-review/references/rq.md +4 -5
  9. package/skills/oracle-grillme/SKILL.md +160 -0
  10. package/skills/oracle-grillme/references/ADR-FORMAT.md +47 -0
  11. package/skills/oracle-grillme/references/CONTEXT-FORMAT.md +63 -0
  12. package/skills/spec-finish/SKILL.md +2 -5
  13. package/skills/spec-implement/SKILL.md +1 -1
  14. package/skills/code-conventional-commit/evals/evals.json +0 -23
  15. package/skills/code-conventional-commit/workspace/iteration-1/eval-0/with_skill/outputs/commit-message.txt +0 -4
  16. package/skills/code-conventional-commit/workspace/iteration-1/eval-0/with_skill/outputs/eval_metadata.json +0 -6
  17. package/skills/code-conventional-commit/workspace/iteration-1/eval-1/with_skill/outputs/eval_metadata.json +0 -6
  18. package/skills/code-conventional-commit/workspace/iteration-1/eval-1/with_skill/outputs/validation-result.txt +0 -16
  19. package/skills/code-conventional-commit/workspace/iteration-1/eval-2/with_skill/outputs/commit-message.txt +0 -8
  20. package/skills/code-conventional-commit/workspace/iteration-1/eval-2/with_skill/outputs/eval_metadata.json +0 -6
  21. package/skills/code-conventional-commit/workspace/iteration-1/report.html +0 -1325
  22. package/skills/code-git-worktrees/SKILL.md +0 -218
  23. package/skills/code-perf/SKILL.md +0 -163
  24. package/skills/code-perf/references/common-bottlenecks.md +0 -124
  25. package/skills/code-perf/references/optimization-patterns.md +0 -167
  26. package/skills/code-perf/references/profiling-tools.md +0 -126
  27. package/skills/code-security/SKILL.md +0 -183
  28. package/skills/code-security/references/owasp-top-10.md +0 -129
  29. package/skills/code-security/references/security-tools.md +0 -102
  30. package/skills/code-security/references/vulnerability-patterns.md +0 -129
  31. package/skills/code-stacked-commit/SKILL.md +0 -155
package/CHANGELOG.md CHANGED
@@ -1,5 +1,22 @@
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
+
12
+ ## [1.0.2](https://github.com/martinffx/atelier/compare/v1.0.1...v1.0.2) (2026-05-23)
13
+
14
+
15
+ ### Bug Fixes
16
+
17
+ * **package:** remove publish script to prevent recursive npm publish ([cbb1420](https://github.com/martinffx/atelier/commit/cbb14200785f0bf73c6e9f60714e3bf774bac5dd))
18
+ * **package:** remove publish script to prevent recursive npm publish in CI ([d2a62dc](https://github.com/martinffx/atelier/commit/d2a62dc3c40301abdf7ddfce86db71c60724b575))
19
+
3
20
  ## [1.0.1](https://github.com/martinffx/atelier/compare/v1.0.0...v1.0.1) (2026-05-23)
4
21
 
5
22
 
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 (34 available)
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,6 +1,6 @@
1
1
  {
2
2
  "name": "@martinffx/atelier",
3
- "version": "1.0.1",
3
+ "version": "1.1.0",
4
4
  "description": "Personal development toolkit - spec-driven development, code quality, deep thinking, and ecosystem patterns",
5
5
  "type": "module",
6
6
  "bin": {
@@ -30,7 +30,6 @@
30
30
  "build": "bun build ./src/atelier.ts --outdir ./dist --target bun",
31
31
  "typecheck": "tsgo --noEmit",
32
32
  "test": "bun test",
33
- "publish": "bun run build && npm publish",
34
33
  "prepare": "simple-git-hooks"
35
34
  },
36
35
  "simple-git-hooks": {
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: code-conventional-commit
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: code-security` - Use the `skill` tool
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
- These skills contain security patterns and TypeScript testing guidance that will help you identify issues.
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: code-perf` (if available) - Use the `skill` tool
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
- - Security concerns → code-security
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", "code-security"]
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", "code-security"]
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", "code-security"]
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 stack: `gt stack`
88
+ 1. Review current commits: `git log --oneline`
91
89
  2. Ensure commits are organized logically
92
- 3. Restack if needed: `gt branch restack`
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-conventional-commit for commit message)
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,4 +0,0 @@
1
- feat(profile): add user profile page with settings modal
2
-
3
- Adds new profile page component displaying user name, email, and
4
- avatar. Includes settings modal for updating user preferences.
@@ -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
- }