JoinedWorkz
Docs1.3.81

Appearance

AI Context ​

JoinedWorkz AI Context is a set of small, structured documents for AI-assisted analysis and development. It supplies framework and project facts that cannot be inferred reliably from generated code alone.

Context is guidance, not a replacement for repository evidence. An AI tool must still inspect the relevant current models, configuration, generators, generated artifacts and manual code before proposing a change.

Resolve the documentation version first

Before loading framework guidance for a project, read its exact Maven plugin version and the versions of all JoinedWorkz facility dependencies. The plugin and every facility must use the same exact JoinedWorkz release. If they differ, report the unsupported version mixture and do not select one release's documentation. Resolve the matching documentation mount through the public machine-readable catalogue at https://www.joinedworkz.org/docs/versions.json. If no matching release is listed, report that gap instead of silently substituting another documentation version.

For a compact framework and ownership summary, start with JoinedWorkz — For AI Tools. For compact CMN modeling guidance, use CMN — For AI Tools. This page defines how those framework references combine with project- and task-specific context.

1. Load context in this order ​

Framework ​

The JoinedWorkz core context explains framework-wide concepts such as CMN, facilities, platforms, cartridges, generators, outlets and build integration. It must remain independent of a concrete product or customer project.

Project ​

Each project owns a separate project context pack. It records only project-specific facts, for example:

  • module and repository structure;
  • consumed facilities and selected platforms;
  • model and configuration locations;
  • outlet routes and Maven source/resource registration;
  • generated/manual integration and runtime boundaries;
  • ownership, cleanup and version-control rules;
  • verified build/test commands and known limitations.

Task ​

The task-specific prompt states the immediate objective, constraints and expected result. Temporary task details do not belong in the framework or project packs.

Current sources ​

After loading Framework → Project → Task, inspect the relevant current repository sources. If context and source evidence disagree, report the drift and verify the current behavior instead of silently choosing one.

2. Ownership must be explicit ​

Before editing or cleaning a file, classify it as:

  1. authoritative input;
  2. manual project source;
  3. replaceable generated output;
  4. first-cut output;
  5. versioned generated history; or
  6. temporary or diagnostic output.

The complete rules are in Generated output, ownership and regeneration.

A path such as src/generated or src/main does not prove ownership. Outlet overrides can route different classes into the same directory or module. Project context should therefore record the source of truth, overwrite/cleanup behavior and version-control policy for every relevant output area.

3. Stateful generation ​

Do not describe every generator as stateless merely because it produces deterministic filenames. Flyway migration generation can depend on an existing schema snapshot and accepted versioned history. Temporary DEVELOPMENT artifacts and persistent STRICT history have different cleanup rules.

For stateful output, the project context must name:

  • the required starting state;
  • the mode or workflow that owns the output;
  • which files may be recreated;
  • which files must be preserved and committed together.

Reproducibility means that the same complete inputs, generator versions and required starting state produce the same result after the declared cleanup.

4. Create a project context pack ​

  1. Open the immutable JoinedWorkz AI Context release matching this documentation.
  2. Check its release and compatibility metadata and require an exact JoinedWorkz compatibility match. Do not use the repository's default branch as an implicit version.
  3. Read the canonical provider- and tool-independent guide for AI agents.
  4. Load the core context pack.
  5. Copy and complete the matching project context template in the concrete project repository.
  6. Keep framework-wide facts in the core pack and project facts in the project pack.
  7. Define a README/metadata entry point and required reading order.
  8. Document ownership and verified project commands from current sources.
  9. Make both packs and the task prompt available to the AI tool, then require source inspection before changes.

The official JoinedWorkz demo repository keeps its project pack under ai/project-context. The AI Context repository also contains a synchronized filled example under templates/project-context-template/examples/joinedworkz-demo/ai/project-context. Treat the demo as one project-specific integration example, not as a mandatory JoinedWorkz structure.

5. Recommended AI workflow ​

  1. Explain the relevant architecture and cite current sources.
  2. Identify the owner and source of truth of every target.
  3. Propose the change at the model, configuration, generator or manual layer that owns it.
  4. Preserve first-cut/manual files, versioned history and required generation state.
  5. Regenerate replaceable output where required.
  6. Validate all affected consumers, review the complete diff and report evidence gaps.

This ordering helps an AI tool distinguish framework behavior from project-specific choices and the immediate task.

6. Related guidance ​