v0.5.0 - Editor, Adoption, Polish

v0.5.0 Roadmap [COMPLETED]

Milestone title: v0.5.0 - Editor, Adoption, Polish

Goal

Make OrgScript feel immediately usable for new contributors and early adopters without expanding the language surface.

Release focus

• editor usability
• README and demo clarity
• curated example quality
• diagnostics and CLI polish
• lightweight language governance

Why now

v0.4.0 established the core developer-experience baseline:

• format --check
• check and check --json
• stable diagnostics with documented codes
• Markdown summary export
• Mermaid demos
• canonical language spec
• governance notes and usage guides
• first usable VS Code syntax highlighting

The next step is not more syntax. The next step is adoption.

Planned issues

1. feat(editor): improve VS Code syntax highlighting
2. docs(readme): add a visual source-to-artifact showcase
3. docs(examples): curate the example catalog
4. enhancement(diagnostics): polish diagnostics UX
5. docs(governance): add language evolution notes

Recommended order

1. VS Code highlighting v2
2. visual README showcase
3. curated example catalog
4. diagnostics UX polish
5. language evolution notes

Workstreams

1. Editor

• refine TextMate scopes
• improve highlighting for block names, references, and operators
• simplify local installation and testing notes
• add one or two visual examples for the editor experience

2. Front door

• show .orgs, Mermaid, and Markdown summary side by side
• make check, validate --json, and lint --json easier to discover
• shorten the path from repository landing to first successful command

3. Examples

• curate three strong examples:
  • sales / lead flow
  • approval / finance
  • service / escalation
• group examples into:
  • simple
  • realistic
  • advanced

4. Diagnostics and CLI polish

• tighten wording of common messages
• preserve diagnostic code stability
• make check output easier to scan
• keep text and JSON behavior aligned

5. Governance

• define what belongs in the language core
• define what should stay in exporters or tooling
• state how breaking changes are handled
• clarify how spec versioning and CLI versioning relate

Non-goals

• new language keywords
• localized syntax
• major parser rewrites
• SaaS or hosted tooling
• enterprise-specific features
• many new exporters at once

Success criteria

• OrgScript feels easier to adopt in a first editor session
• the README demonstrates visible value in under a minute
• examples are easier to browse and compare
• diagnostics feel more polished without changing the language core
• language evolution decisions become easier to reason about

Next after v0.5.0

v0.6.0 should focus on integrations and generated artifacts:

• Mermaid stabilization
• richer Markdown or HTML docs
• clearer exporter contracts
• stronger source-to-artifact demo flows

v0.4.0 — check command, markdown export, unified diagnostics, and initial VS Code highlighting

OrgScript v0.4.0

OrgScript v0.4.0 is the first developer-experience release.

This release moves the project from a stable language/tooling core toward a more usable day-to-day workflow with combined quality checks, documented machine-readable diagnostics, visible downstream exports, and the first usable editor integration.

Highlights

• canonical formatting checks via format --check
• one-command quality verification via check
• stable diagnostics with documented codes and JSON output
• Markdown summary export
• Mermaid demos for process and stateflow visualization
• canonical language spec, governance notes, and usage guides
• first usable VS Code syntax-highlighting extension for .orgs

CLI and DX

• Added orgscript format <file> --check
• Added orgscript format <file> --check --json
• Added orgscript check <file>
• Added orgscript check <file> --json
• Added npm run check:all
• Integrated canonical formatting checks into CI
• Unified CLI diagnostics across validate, lint, check, and format --check
• Introduced stable diagnostic code namespaces for cli, syntax, semantic, lint, and format

Exports and visible outputs

• Added orgscript export markdown <file> for deterministic Markdown summaries
• Added Mermaid demo artifacts and generation flow
• Kept Mermaid export available for process and stateflow
• Extended demo material under docs/demos

Language maturity

• Added the canonical spec/language-spec.md
• Added governance guidance and authoring guides for humans and AI
• Expanded the diagnostics contract in spec/diagnostics.md
• Kept CI and golden snapshots green on the combined quality path

Editor support

• Upgraded the VS Code OrgScript extension from a scaffold to a usable first TextMate-based syntax-highlighting integration
• Registered .orgs files as OrgScript
• Highlighted top-level blocks, statements, section keywords, strings, booleans, numbers, operators, and dotted references
• Documented local testing in editors/vscode/README.md

Verification

Verified with:

• npm test
• npm run check:all
• node ./bin/orgscript.js check ./examples/craft-business-lead-to-order.orgs
• node ./bin/orgscript.js check ./examples/craft-business-lead-to-order.orgs --json
• node ./bin/orgscript.js export markdown ./examples/order-approval.orgs
• node ./bin/orgscript.js export mermaid ./examples/order-approval.orgs

Project status

OrgScript is not a programming language.
It is a human-readable, AI-interpretable description language for business logic, processes, rules, roles, policies, events, and operational systems.

v0.4.0 is the first release where OrgScript feels usable not only as a language implementation, but also as a contributor-facing tooling project.

v0.3.0 — Formatter, linter, diagnostics, and CI readiness

OrgScript v0.3.0

OrgScript v0.3.0 is the first quality-tooling release.

This release rounds out the initial implementation baseline with deterministic formatting, stable golden snapshots, an AST-based linter, machine-readable diagnostics, and CI-ready CLI behavior.

Highlights

• AST-backed canonical formatter
• Golden snapshot freeze for AST, canonical model, and formatted output
• AST-based linter with stable severities and deterministic reporting
• Human and AI usage guides
• JSON diagnostics for validate and lint
• First GitHub Actions CI workflow

Added

• orgscript format <file>
• orgscript lint <file>
• orgscript validate <file> --json
• orgscript lint <file> --json
• scripts/lint-all.js
• .github/workflows/ci.yml
• docs/orgscript-for-humans.md
• docs/orgscript-for-ai.md
• spec/diagnostics.md

Changed

• Lint exit codes are now CI-friendly:
  • 0 when findings contain only warning and info
  • 1 when findings contain at least one error
• Validation and lint diagnostics now have a machine-readable JSON contract
• Formatter, AST, and canonical model output are frozen through golden snapshots
• Lint output is stable and sorted deterministically

Verification

Verified with:

• npm test
• npm run validate:all
• npm run lint:all

Project status

OrgScript is not a programming language.
It is a human-readable, AI-interpretable description language for business logic, processes, rules, roles, policies, events, and operational systems.

v0.3.0 is the first release that makes OrgScript feel stable as tooling, not only as a language implementation.