md-ddl 0.9.2__tar.gz

md_ddl-0.9.2/.claude/commands/agent-architect.md

@@ -0,0 +1,10 @@
+Read `agents/agent-architect/AGENT.md` and adopt its identity, modes, and protocols for this session.
+
+Follow the skill-loading protocol defined in the AGENT.md:
+- Identify which skill(s) apply to the request below (architecture, product-design, odps-alignment)
+- Read those `agents/agent-architect/skills/<skill>/SKILL.md` files before responding
+- For product design, read the relevant domain files before drafting product declarations
+
+Produce production-quality data product declarations and ODPS manifests. Do not model domain entities or generate physical artifacts — those belong to Agent Ontology and Agent Artifact respectively.
+
+Task: $ARGUMENTS

md_ddl-0.9.2/.claude/commands/agent-artifact.md

@@ -0,0 +1,10 @@
+Read `agents/agent-artifact/AGENT.md` and adopt its identity, modes, and protocols for this session.
+
+Follow the skill-loading protocol defined in the AGENT.md:
+- Identify which skill(s) apply to the request below (dimensional, normalized, wide-column, knowledge-graph)
+- Read those `agents/agent-artifact/skills/<skill>/SKILL.md` files before responding
+- Read the relevant domain and product files from the examples or the user's working directory before generating artifacts
+
+Generate physical artifacts (SQL DDL, JSON Schema, Parquet schema, Cypher) scoped by the data product declaration. Do not change the domain model — flag conceptual gaps and defer structural changes to Agent Ontology.
+
+Task: $ARGUMENTS

md_ddl-0.9.2/.claude/commands/agent-governance.md

@@ -0,0 +1,11 @@
+Read `agents/agent-governance/AGENT.md` and adopt its identity, modes, and protocols for this session.
+
+Follow the skill-loading protocol defined in the AGENT.md:
+- Identify which skill(s) apply to the request below (standards-conformance, regulatory-compliance, compliance-audit)
+- Read those `agents/agent-governance/skills/<skill>/SKILL.md` files before responding
+- For regulatory audits, read the relevant regulator file from `agents/agent-governance/skills/regulatory-compliance/regulators/`
+- Read the domain files being audited before producing findings
+
+Produce governance findings, gap reports, and remediation recommendations. Do not make structural model changes — flag gaps and defer them to Agent Ontology or Agent Architect.
+
+Task: $ARGUMENTS

md_ddl-0.9.2/.claude/commands/agent-guide.md

@@ -0,0 +1,10 @@
+Read `agents/agent-guide/AGENT.md` and adopt its identity, modes, and protocols for this session.
+
+Follow the skill-loading protocol defined in the AGENT.md:
+- Identify which skill(s) apply to the request below (Orientation, Concept Explorer, Worked Examples, Platform Setup)
+- Read those `agents/agent-guide/skills/<skill>/SKILL.md` files before responding
+- If no specific skill is identified, default to Welcome mode
+
+Do not generate production MD-DDL. Teach, demonstrate, and navigate. When the user is ready for production work, name the receiving agent and offer to formulate their opening prompt.
+
+Task: $ARGUMENTS

md_ddl-0.9.2/.claude/commands/agent-ontology.md

@@ -0,0 +1,10 @@
+Read `agents/agent-ontology/AGENT.md` and adopt its identity, modes, and protocols for this session.
+
+Follow the skill-loading protocol defined in the AGENT.md:
+- Identify which skill(s) apply to the request below (domain-scoping, entity-modelling, relationship-events, standards-alignment, source-mapping, domain-review)
+- Read those `agents/agent-ontology/skills/<skill>/SKILL.md` files before responding
+- If the skill references spec sections, read the relevant `md-ddl-specification/*.md` files before drafting
+
+Produce production-quality MD-DDL. Follow the output rules in the AGENT.md. Do not generate physical artifacts — that is Agent Artifact's responsibility.
+
+Task: $ARGUMENTS

md_ddl-0.9.2/.github/agents/agent-architect.agent.md

@@ -0,0 +1,11 @@
+---
+name: agent-architect
+description: Specialist MD-DDL strategic design and data product publication agent for architecture philosophy discussion, data product declaration, product class and schema type selection, governance and masking strategies, and ODPS-aligned manifest generation.
+argument-hint: An architecture discussion topic, an MD-DDL domain to design data products for, consumer needs and access patterns, or existing products to publish as ODPS manifests.
+tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'web', 'todo']
+---
+Canonical source: `../../.md-ddl/agents/agent-architect/AGENT.md`
+
+<agent_architect_core>
+{{INCLUDE: ../../.md-ddl/agents/agent-architect/AGENT.md}}
+</agent_architect_core>

md_ddl-0.9.2/.github/agents/agent-artifact.agent.md

@@ -0,0 +1,11 @@
+---
+name: agent-artifact
+description: Specialist MD-DDL physical artifact generation agent for dimensional star schemas, normalized 3NF designs, SQL DDL, JSON Schema, and Parquet schema contracts.
+argument-hint: An MD-DDL domain to generate physical artifacts from, a target physical style (dimensional/3NF), and a platform dialect.
+tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'web', 'todo']
+---
+Canonical source: `../../.md-ddl/agents/agent-artifact/AGENT.md`
+
+<agent_artifact_core>
+{{INCLUDE: ../../.md-ddl/agents/agent-artifact/AGENT.md}}
+</agent_artifact_core>

md_ddl-0.9.2/.github/agents/agent-governance.agent.md

@@ -0,0 +1,11 @@
+---
+name: agent-governance
+description: Specialist MD-DDL standards conformance and compliance assurance agent for auditing standards alignment, regulatory compliance, governance metadata completeness, and guiding remediation across domain portfolios.
+argument-hint: A domain or corpus to audit, applicable standards or jurisdictions/frameworks, or a compliance posture and remediation request.
+tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'web', 'todo']
+---
+Canonical source: `../../.md-ddl/agents/agent-governance/AGENT.md`
+
+<agent_governance_core>
+{{INCLUDE: ../../.md-ddl/agents/agent-governance/AGENT.md}}
+</agent_governance_core>

md_ddl-0.9.2/.github/agents/agent-guide.agent.md

@@ -0,0 +1,11 @@
+---
+name: agent-guide
+description: Learning companion and navigator for the MD-DDL ecosystem — the first place to go for understanding the standard, exploring concepts, walking through examples, setting up your environment, and finding the right specialist agent.
+argument-hint: A question about MD-DDL, a request for help getting started, or guidance on which agent to use for a specific task.
+tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'web', 'todo']
+---
+Canonical source: `../../.md-ddl/agents/agent-guide/AGENT.md`
+
+<agent_guide_core>
+{{INCLUDE: ../../.md-ddl/agents/agent-guide/AGENT.md}}
+</agent_guide_core>

md_ddl-0.9.2/.github/agents/agent-ontology.agent.md

@@ -0,0 +1,11 @@
+---
+name: agent-ontology
+description: Specialist MD-DDL modelling agent for domain discovery, entity design, relationships/events, and standards-aligned domain authoring.
+argument-hint: A domain to model, existing MD-DDL files to improve, or a modelling question requiring trade-offs and rule validation.
+tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'web', 'todo']
+---
+Canonical source: `../../.md-ddl/agents/agent-ontology/AGENT.md`
+
+<agent_ontology_core>
+{{INCLUDE: ../../.md-ddl/agents/agent-ontology/AGENT.md}}
+</agent_ontology_core>

md_ddl-0.9.2/.github/agents/review-md-ddl.agent.md

@@ -0,0 +1,46 @@
+---
+name: review-md-ddl
+description: Run structured reviews of the MD-DDL standard, agents, and examples using a layered process — structural checks, adversarial probing, and stakeholder simulation. Use this when asked to review, evaluate, audit, or assess the standard.
+argument-hint: A review request — e.g. "review the standard", "find weaknesses", "evaluate for users", or "full layered review".
+tools: ['vscode', 'execute', 'read', 'search', 'todo']
+---
+
+# Review MD-DDL
+
+You are a review agent for the MD-DDL project. You run structured, honest reviews
+of the standard, agents, skills, and examples.
+
+## Before anything else
+
+Read the layered review process document:
+
+<review_process>
+{{INCLUDE: ../../.prompts/md-ddl-layered-review-process.md}}
+</review_process>
+
+## Determining which layer to run
+
+Based on the user's request, select the appropriate layer:
+
+Request pattern | Layer | Prompt to load
+--- | --- | ---
+"Review" / "check" / "structural review" | Layer 1 | `.prompts/md-ddl-review-prompt.md`
+"Find weaknesses" / "adversarial" / "stress test" / "what's wrong" | Layer 2 | `.prompts/md-ddl-adversarial-review-prompt.md`
+"Evaluate" / "stakeholder" / "would users adopt" / "personas" | Layer 3 | `.prompts/md-ddl-evaluation-prompt.md`
+"Full review" / "layered review" / "comprehensive" | All layers | Run 1 → 2 → 3 in order
+
+If ambiguous, ask the user which layer they want. If they say "just review it,"
+default to Layer 1 (structural) as it's the fastest and most objectively verifiable.
+
+## Loading the review prompt
+
+Once you've determined the layer, read the corresponding prompt file listed above.
+That file contains the full review protocol — follow it completely.
+
+## Non-negotiable rules
+
+- Every review report must include a "What I Cannot Evaluate" section.
+- Never soften findings. If something is broken, say it's broken.
+- Scores of 5/5 require specific evidence of excellence. Do not default to high scores.
+- An honest review that finds real issues is more valuable than a clean bill of health.
+- Write findings to `review.md` as instructed by the loaded prompt.

md_ddl-0.9.2/.gitignore

@@ -0,0 +1,215 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.continue
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Generated Financial Crime physical model outputs
+examples/Financial Crime/generated/
+
+review.md
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+.claude/settings.local.json

md_ddl-0.9.2/CLAUDE.md

@@ -0,0 +1,111 @@
+# MD-DDL Project
+
+This is the **source repository** for the MD-DDL standard — its specification, agent prompts, skills, and examples.
+
+## Agents
+
+MD-DDL provides AI agents for every stage of the modelling lifecycle.
+Invoke them with slash commands or let the auto-routing below guide you.
+
+Command | Agent | Purpose
+--- | --- | ---
+`/agent-guide` | Agent Guide | Learning, navigation, concept explanation. Start here.
+`/agent-ontology` | Agent Ontology | Domain discovery, entity modelling, source mapping.
+`/agent-artifact` | Agent Artifact | Physical schema generation (SQL DDL, JSON Schema, Parquet, Cypher).
+`/agent-architect` | Agent Architect | Data product design, architecture discussion, ODPS manifests.
+`/agent-governance` | Agent Governance | Standards conformance, compliance auditing, governance assurance.
+
+Agent prompts: `agents/<agent-name>/AGENT.md`
+
+## Auto-Routing
+
+When no slash command is given, select the appropriate agent based on the request:
+
+Request type | Agent to activate
+--- | ---
+"What is...", "How does...", "Explain...", onboarding | Read `agents/agent-guide/AGENT.md`
+Modelling a domain, designing entities, mapping sources | Read `agents/agent-ontology/AGENT.md`
+Brownfield adoption, "we already have", existing systems, import schema | Read `agents/agent-ontology/AGENT.md` (baseline-capture or schema-import skill)
+Generating DDL, JSON Schema, Parquet, Cypher | Read `agents/agent-artifact/AGENT.md`
+Reconcile generated vs existing, gap analysis | Read `agents/agent-artifact/AGENT.md` (reconciliation skill)
+Data product design, architecture, ODPS | Read `agents/agent-architect/AGENT.md`
+Compliance audit, governance review, standards check | Read `agents/agent-governance/AGENT.md`
+Review, evaluate, audit the standard itself | Read `.prompts/md-ddl-layered-review-process.md` for orchestration, then load the appropriate layer prompt from `.prompts/`
+
+When activating an agent, also follow its skill-loading protocol — read the applicable `SKILL.md` files before responding.
+
+## Validation
+
+MD-DDL uses **agent-driven quality review**, plus lightweight linting. The two-tier validation model (mechanical pre-flight checks for syntax + agent-driven review for everything else) is defined in `1-Foundation.md`. Agents work with organisational deviations from convention rather than rejecting them — deviations are observations and potential spec contributions, not errors.
+
+The linter lives at `src/md_ddl/lint.py`. Run it in this repo with `python scripts/md_ddl_lint.py <domain-folder>`; installed from PyPI it is `md-ddl lint <domain-folder>`.
+
+## Packaging
+
+This repository is also the `md-ddl` PyPI distribution. `src/md_ddl/` holds the package; `pyproject.toml` force-includes `agents/`, `md-ddl-specification/`, `guides/`, `examples/`, and `references/architecture/` as package data, and the agent wrappers from `.github/agents/` and `.claude/commands/`. `references/industry_standards/` is deliberately excluded — 63 MB of raw snapshots.
+
+`md-ddl init` unpacks that payload into a consuming project's `.md-ddl/`, mirroring what the submodule flow in `scripts/start-project.sh` does. When you add an agent, a spec section, or a guide, it is packaged automatically; when you add a new *top-level* directory that agents read, add it to `DOCS_PAYLOAD` in `src/md_ddl/__init__.py` and to the force-include table in `pyproject.toml`.
+
+`{{INCLUDE: ...}}` directives must use file-relative paths so they resolve both in this repo and from `.md-ddl/` in a consuming project. `src/md_ddl/includes.py` implements the check; `md-ddl init` runs it after unpacking and `md-ddl check` re-runs it on demand.
+
+Releases publish from `.github/workflows/publish.yml` via PyPI Trusted Publishing. Bump `__version__` in `src/md_ddl/__init__.py`, tag `v<version>`, publish a GitHub release.
+
+## Review Output
+
+All review, evaluation, and post-mortem outputs must be written to `roadmap/review/`,
+prefixed with the date in `YYYY-MM-DD` format. Examples:
+
+- `roadmap/review/2026-03-15-layer1-structural-review.md`
+- `roadmap/review/2026-03-15-consolidated-review.md`
+- `roadmap/review/2026-03-15-post-mortem-<topic>.md`
+
+This applies whenever a user requests:
+
+- A review of the spec, agents, examples, or repository structure
+- A post-mortem on a completed piece of work
+- Any evaluation, audit, or findings document intended to inform the roadmap
+
+The `.prompts/` files contain the prompts for each layer of review. Each prompt
+already includes the correct output path instruction.
+
+## Working Style
+
+### Sequential Execution
+
+- **Never spin up parallel subagents or background agents for implementation
+  work.** One task at a time, completed and verified before moving to the next.
+- When implementing a plan with multiple items, create a TodoWrite task list at
+  the start covering every item, then mark each complete before proceeding.
+- Do not batch multiple file writes across unrelated items in a single response.
+  Each plan item is its own step: write → verify → mark done → proceed.
+- When a plan item requires reading files before writing, do the reads first
+  in a single step, then write in the next.
+
+### Resuming After Interruption
+
+If the conversation starts mid-plan, or the user indicates work was cut off:
+
+1. Run `git status` to identify which files have been modified since the last commit
+2. Read any recently modified files to confirm their current state
+3. Cross-reference against the plan to identify the last completed item
+4. State what has been done and what remains before proceeding — do not
+   silently re-do completed work or skip ahead
+
+This keeps incomplete work recoverable without re-reading the full conversation
+history or repeating already-finished steps.
+
+## Architectural Philosophy
+
+MD-DDL implements the **Data Autonomy** architectural style. See `references/architecture/` for foundational blog posts and external references, and `agents/agent-architect/skills/architecture/SKILL.md` for the distilled 13 tenets.
+
+## Key References
+
+- MD-DDL specification: `md-ddl-specification/`
+- Foundation principles: `md-ddl-specification/1-Foundation.md`
+- Complete spec (single file for AI context): `md-ddl-specification/MD-DDL-Complete.md`
+- Architectural philosophy and tenets: `agents/agent-architect/skills/architecture/SKILL.md`
+- Architecture source material: `references/architecture/`
+- Examples: `examples/`
+- Review and evaluation prompts: `.prompts/`
+- Review outputs: `roadmap/review/`
+- Spec concatenation rules: `.prompts/concat-md-ddl-specs.prompt.md`