// Validates structural or foundational code changes against Camunda architecture principles. Use when a change alters module boundaries, APIs, data flows, core architecture, domain models, or protocols.
| name | check-architecture-principles |
| description | Validates structural or foundational code changes against Camunda architecture principles. Use when a change alters module boundaries, APIs, data flows, core architecture, domain models, or protocols. |
| compatibility | Requires gh CLI (preferred) or the `github` MCP server as fallback |
| metadata | {"author":"camunda"} |
Use this skill before implementing any structural or foundational change:
Do not use for linear changes (flags, constants, simple feature tweaks).
Try gh first. Fall back to GitHub MCP if gh is unavailable or returns an error (e.g., 404 may indicate missing authentication).
Primary — gh CLI:
# List principle documents
gh api repos/camunda/product-development/contents/architecture/principles --jq '.[].name'
# Read a specific principle
gh api repos/camunda/product-development/contents/architecture/principles/{filename} --jq '.content' | base64 -d
Fallback — github MCP server:
Use the github MCP server to read the contents of architecture/principles in the camunda/product-development repo. Use this when gh is not available (e.g., web UI environments).
Read each principle document found.
For each principle, evaluate whether the planned change conforms or conflicts. Produce a checklist:
Architecture Conformance:
- [ ] Principle: [name] — [conformant / not applicable / conflict]
If any principle conflicts with the planned change:
If all principles are conformant or not applicable, proceed with implementation.
Review an engineering spec, design doc, or WIP RFC through a product-sense lens — problem framing, user fit, product fit, and whether the spec is framed clearly enough for the team to act on it. Calibrates to the spec's maturity stage (early direction, partial spec, ready-for-define) so early-stage work gets direction feedback, not premature spec polish. Use before implementation begins, on work-in-progress specs. Output is a structured review posted inline in the conversation — does NOT write files to the working directory. Triggers on: "review this spec", "review this RFC", "review this design", "PM review", "spec review", "product-sense review", a GitHub issue/PR link containing a spec body, a Google Doc design doc link, or a pasted spec. Use when user: asks for a structured review of an engineering proposal before Define/build; needs to surface cross-product dependencies or hidden deferrals; wants to validate problem framing, scope, and edge states before committing to implementation; or wants a second o
Create an Architecture Decision Record (ADR) as a Markdown file. Triggers on: "write an ADR", "capture this decision", "migrate this doc into an ADR", architecture folder, decision records, ADR numbering/renumbering, and requests to turn a Google Doc / kickoff note / conversation outcome into a durable decision record. Use when user: asks to create or migrate an ADR, records a just-made architectural decision, adds a decision to an existing ADR folder (e.g. docs/adrs/), or needs to align a draft with the house ADR format.
Writes documentation for the current code changes and raises a PR to camunda/camunda-docs — or updates an existing docs PR if one is already open for this branch.
Searches Camunda 8 documentation for domain knowledge needed during implementation. Use when a change involves Camunda-specific concepts, APIs, configuration, or behavior — such as BPMN, DMN, Zeebe, Connectors, Operate, Tasklist, Identity, or any Camunda platform component.