Skip to content

Commit 0e28aba

Browse files
akoclaude
ako
and
claude
committed
feat: add contributor workflow commands and session welcome
Adds /mxcli-dev:proposal command that guides contributors through creating a feature proposal: understanding the feature, investigating BSON structure with real .mpr files, checking for overlap, designing MDL syntax per the design skill, and writing the proposal in the standard format. Updates /mxcli-dev:review with recurring finding #9 (doc comments promising features that don't exist) from the marketplace review. Adds a "Welcome — Contributing to mxcli" section at the top of CLAUDE.md so new sessions start with a clear pointer to the contribution workflow, the available /mxcli-dev:* commands, and the local validation steps. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent ea52a5f commit 0e28aba

File tree

3 files changed

+175
-0
lines changed

3 files changed

+175
-0
lines changed

‎.claude/commands/mxcli-dev/proposal.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# /mxcli-dev:proposal — Create Feature Proposal
2+
3+
Guide the contributor through creating a well-structured feature proposal for
4+
mxcli. The proposal goes in `docs/11-proposals/PROPOSAL_<name>.md`.
5+
6+
## Process
7+
8+
Work through these phases **interactively** — ask the user questions, don't
9+
guess. Each phase produces concrete output.
10+
11+
### Phase 1: Understand the Feature
12+
13+
Ask the user:
14+
15+
1. **What** do you want to add? (one sentence)
16+
2. **Why** — what problem does this solve, or what user story does it enable?
17+
3. **Which Mendix version** introduced this capability? (affects version-gating)
18+
4. **Does this add MDL syntax?** (CREATE/ALTER/DROP/SHOW/DESCRIBE statements)
19+
5. **Does this touch BSON serialization?** (reading or writing Mendix documents)
20+
21+
If the user isn't sure about version or BSON, help them find out:
22+
- Version: check `reference/mendixmodellib/reflection-data/` or Mendix release notes
23+
- BSON: check if similar features exist in `sdk/mpr/parser*.go` or `sdk/mpr/writer*.go`
24+
25+
### Phase 2: BSON Investigation (if applicable)
26+
27+
**CRITICAL**: If the feature reads or writes Mendix documents, investigate the
28+
BSON structure BEFORE designing syntax. Wrong assumptions here cause CE errors
29+
in Studio Pro that are painful to debug.
30+
31+
1. **Find a working example** — ask the user:
32+
- "Do you have a test `.mpr` project with this feature already configured in Studio Pro?"
33+
- If yes: use `mxcli bson dump` or `mxcli bson discover` to extract the BSON structure
34+
- If no: ask them to create a minimal example in Studio Pro first
35+
36+
2. **Extract the BSON structure**:
37+
```bash
38+
# Find the document type
39+
./bin/mxcli -p project.mpr -c "SHOW STRUCTURE ALL" | grep -i <feature-name>
40+
41+
# Dump the raw BSON
42+
./bin/mxcli bson dump -p project.mpr --type "<BSON $Type>"
43+
44+
# Or discover all instances of a type
45+
./bin/mxcli bson discover -p project.mpr --pattern "<pattern>"
46+
```
47+
48+
3. **Document the BSON structure** in the proposal:
49+
- Storage name (`$Type` field) — verify against `reference/mendixmodellib/reflection-data/`
50+
- All fields with types and observed values
51+
- Any fields that use Mendix-internal IDs (pointers to other documents)
52+
- Note any counter-intuitive naming (like Parent/Child pointer inversion)
53+
54+
4. **Check for storage-name vs qualified-name mismatches** — consult the table
55+
in CLAUDE.md under "BSON Storage Names vs Qualified Names". If the feature
56+
uses a type that has a known mismatch, document it prominently.
57+
58+
### Phase 3: Check for Overlap
59+
60+
Before writing the proposal, search for existing work:
61+
62+
```bash
63+
# Existing proposals
64+
ls docs/11-proposals/ | grep -i <feature>
65+
66+
# Existing implementations
67+
grep -r "<feature>" mdl/executor/ sdk/mpr/ --include="*.go" -l
68+
69+
# Existing test coverage
70+
ls mdl-examples/doctype-tests/ | grep -i <feature>
71+
```
72+
73+
If there's overlap, discuss with the user whether to extend the existing work
74+
or start fresh.
75+
76+
### Phase 4: Design MDL Syntax (if applicable)
77+
78+
If the feature adds MDL statements, read `.claude/skills/design-mdl-syntax.md`
79+
first, then design syntax that follows these principles:
80+
81+
- Uses standard verbs: `CREATE`, `ALTER`, `DROP`, `SHOW`, `DESCRIBE`
82+
- Reads as English — a business analyst understands it
83+
- Uses `Module.Element` qualified names everywhere
84+
- Property format: `( Key: value, ... )` with colon separators
85+
- One example is enough for an LLM to generate correct variants
86+
- Adding one property is a one-line diff
87+
88+
Present the proposed syntax to the user and ask for feedback before proceeding.
89+
90+
### Phase 5: Write the Proposal
91+
92+
Create `docs/11-proposals/PROPOSAL_<snake_case_name>.md` with this structure:
93+
94+
```markdown
95+
# Proposal: <Title>
96+
97+
**Status:** Draft
98+
**Date:** <today's date>
99+
100+
## Problem Statement
101+
102+
<What problem does this solve? Who benefits?>
103+
104+
## BSON Structure
105+
106+
<Document the storage format. Include the $Type, all fields, pointer
107+
relationships, and any gotchas. If not applicable, explain why.>
108+
109+
## Proposed MDL Syntax
110+
111+
<Show CREATE/ALTER/DROP/SHOW/DESCRIBE examples. If not MDL syntax,
112+
describe the CLI commands or API changes.>
113+
114+
## Implementation Plan
115+
116+
<Which files need to change? What's the order of operations?>
117+
118+
### Files to modify/create
119+
120+
| File | Change |
121+
|------|--------|
122+
| `mdl/grammar/MDLParser.g4` | Add rule for ... |
123+
| `mdl/ast/...` | New AST node |
124+
| ... | ... |
125+
126+
## Version Compatibility
127+
128+
<Which Mendix version introduced this? Does it need version-gating?>
129+
130+
## Test Plan
131+
132+
<What test scripts go in mdl-examples/doctype-tests/? What roundtrip
133+
tests are needed?>
134+
135+
## Open Questions
136+
137+
<What's unresolved? What needs user input or further investigation?>
138+
```
139+
140+
### Phase 6: Confirm with User
141+
142+
Show the user the proposal and ask:
143+
- "Does this look right?"
144+
- "Anything I should add or change?"
145+
- "Ready to commit?"
146+
147+
If confirmed, commit the proposal file.
148+
149+
---
150+
151+
## Important Reminders
152+
153+
- **Never guess BSON field names.** Always verify against a real `.mpr` file or
154+
the reflection data. Wrong field names cause silent data corruption.
155+
- **Don't skip the BSON investigation** for features that touch Mendix documents.
156+
The proposal will be wrong without it, and the implementation will produce
157+
CE errors in Studio Pro.
158+
- **Check existing proposals first.** The `docs/11-proposals/` directory has 30+
159+
proposals — some may cover the same ground or provide useful reference.

‎.claude/commands/mxcli-dev/review.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ proactively. Add a row after every review that surfaces something new.
3131
| 6 | Docs-only PR cites an unmerged PR as a "model example" — cited PR had blockers | Docs quality | Only cite merged, verified PRs; or annotate with known gaps if citing in-flight work |
3232
| 7 | Skill/doc table references a function that doesn't exist (e.g. `formatActionStatement()` vs `formatAction()`) | Docs quality | Grep function names before writing: `grep -r "func formatA" mdl/executor/` |
3333
| 8 | "Always X" rule is too absolute for trivial edge cases (e.g. "always write failing test first" for one-char typos) | Docs quality | Soften to "prefer X" or add an exception clause; include the reasoning so readers can judge edge cases |
34+
| 9 | Doc comment promises a fallback/feature that doesn't exist in the code (e.g., "raw-map fallback in the client" when no such fallback was implemented) | Docs quality | Grep for function/type names referenced in doc comments to confirm they exist before committing |
3435

3536
---
3637

‎CLAUDE.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,21 @@
22

33
This file provides guidance for Claude Code when working with this repository.
44

5+
## Welcome — Contributing to mxcli
6+
7+
If you're starting a new task, here's how contributions work in this repo:
8+
9+
1. **File an issue first** — describe the bug or feature before coding. See `CONTRIBUTING.md` for details.
10+
2. **Get approval** — wait for maintainer sign-off before starting work.
11+
3. **Create a feature branch** — `feature/123-short-description` or `fix/456-what-broke`.
12+
4. **Use the contributor commands** to stay on track:
13+
- `/mxcli-dev:proposal` — create a structured feature proposal (asks the right questions, investigates BSON storage)
14+
- `/mxcli-dev:review` — review your changes against the PR checklist before pushing
15+
5. **Validate locally** — `make build && make test && make lint` must all pass.
16+
6. **Open a PR** — link the issue, document Mendix Studio Pro validation, confirm agentic testing.
17+
18+
For the full workflow, read `CONTRIBUTING.md`. For the review checklist applied to every PR, see the "PR / Commit Review Checklist" section below.
19+
520
## Project Overview
621

722
**ModelSDK Go** is a Go library for reading and modifying Mendix application projects (`.mpr` files) stored locally on disk. It's a Go-native alternative to the TypeScript-based Mendix Model SDK, enabling programmatic access without cloud connectivity.

0 commit comments

Comments
 (0)