Morph Agent Instructions

These instructions apply to the whole repository.

Non-Negotiable Workflow

• Do not run cmake -S ..., cmake --build ..., or raw generator commands directly for normal build/test work.
• Use morphc — the unified build system.
• If you need build + tests together, prefer a single command:
  • morphc.bat build --test
• Do not start morphc test while another build is already running in the background. Wait for the build to finish, or use morphc.bat build --test ... instead.
• For full build + full tests on Windows:
  • morphc.bat build --test
• For targeted tests:
  • morphc.bat test "pattern"
• For environment diagnostics:
  • morphc.bat doctor
• Toolchain (MSYS2, LLVM, Ninja) is auto-detected. No environment variables needed.

Build Commands Reference

Command	Description
morphc build	Smart incremental build (auto-reconfigure if manifests changed)
morphc build --clean	Clean reconfigure + build
morphc build --debug	Debug build
morphc build -t <target>	Build specific cmake target
morphc build --test	Build once, then run full tests
morphc build --test "flow"	Build once, then run filtered tests
morphc test	Build + run unit tests + package-owned behavior suites
morphc test "flow"	Build + run unit tests matching pattern (skips package-owned behavior suites)
morphc test --unit-only	Run only C++ unit tests, skip package-owned behavior suites
morphc test --list	List available unit tests
morphc configure	Just (re)configure cmake
morphc configure --clean	Force clean reconfigure
morphc clean	Remove build directory
morphc doctor	Diagnose build environment
morphc status	Show build state and history
morphc watch	Watch for changes, auto-rebuild

Why This Matters

• The build system auto-detects MinGW/LLVM/Ninja toolchain.
• It tracks morph manifest hashes and auto-reconfigures when they change.
• Structured error parsing shows compiler/linker errors clearly.
• Build history is tracked for debugging.

Project Facts

• This repository is the Morph compiler/runtime/tooling project, not a generated app.
• Important roots:
  • src/: compiler, CLI, NCON, build pipeline
  • runtime/: runtime and platform backends
  • include/: public headers
  • tests/: C++ unit tests (morph_unit_tests)
  • morphs/: package manifests, package-owned runtime/features, and package-owned behavior suites under morphs/*/tests/
  • scripts/morphc_build/: build system Python package

Current Package System Rules

• Dependency manifest: morph.toml
• Lockfile: morph.lock
• Local installed packages: modules/<package>/
• Global package cache/store on Windows: %APPDATA%\Morph\packages (from generated branding / PackageManager)
• Canonical dependency syntax is inline table:
  • foo = { github = "owner/repo", version = "^1.2.0" }
• Canonical native config is top-level [modulecpp] and [modulecpp.<Name>]
• Legacy [ncon.modulecpp.<Name>] and [ncon.native] still parse as aliases

When Editing

• Preserve existing user changes.
• Add or update tests for behavior changes.
• After meaningful code changes, rerun the build: morphc build

Detailed References

• Reusable system prompt: SYSTEM_PROMPT.md
• Build/test playbook: BUILD_AND_TEST.md