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. Inspect the current sources relevant to a change; descend into implementation details when a specific question remains open or observed behavior contradicts the guidance.

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 ​

Task → Project → Framework ​

Start with the task's objective, constraints and expected result, then follow the project's entry document. In projects created with Maven Archetypes 1.3.0, AGENTS.md points to ai/project-context/README.md.

Read the project entry and development rules. They identify the actual dependencies, selected Platforms, ownership boundaries and commands. Follow their Framework links for the task's relevant features. The Framework Core requires only its README.md and 13-ai-usage-instructions.md initially; load other topics when needed. Reuse knowledge already present in context.

Project facts ​

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.

Framework knowledge ​

The Core explains reusable concepts, CMN, Profiles, Facilities, Cartridges, generators, Outlets and build integration. It does not know a concrete project. Project context refers to Framework knowledge, never the reverse. Temporary task details belong in the task, not in either context pack.

Current sources ​

Inspect the relevant current repository sources. If context and source evidence disagree, report the drift and verify the affected behavior instead of silently choosing one. If a required linked document cannot be read, provide it locally or report the missing knowledge; do not treat a truncated read as the complete document.

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 ​

AI Context 2.0.0 describes Framework compatibility with JoinedWorkz 1.3.81. Its Context version is independent of both the Framework release and Maven Archetypes 1.3.0. Core metadata records version separately from compatibility.joinedworkz_version.

Projects created with Archetypes 1.3.0 ​

Both starters include the complete Framework Core at ai/joinedworkz-context-core/ and a populated project context at ai/project-context/. The project documents are parameterized for the project name, Maven coordinates, Java package, database and, where applicable, frontend delivery. Use these local files; another repository checkout or live web access is not required to read them.

The backend-only starter also includes the Quasar knowledge. Available documentation does not activate a Facility or require reading it. Project configuration determines which Platforms are used. Maintain project context alongside changes to the actual application.

ai/project-context/project-context.meta.json records the Core source repository, AI Context version (2.0.0) and path, plus Archetype coordinates, in initial_context_distribution. framework_context_source.version identifies the supplied Context version, not subsequent application changes.

Existing projects ​

  1. Obtain the Framework Core from the canonical AI Context repository. Check joinedworkz.meta.json for the Context version and exact Framework compatibility; these are independent version numbers.
  2. Keep a local copy of the Core and its license notices available to the agent. Load only the entry, usage rules and relevant topic files.
  3. Copy and complete the project context template from the same source checkout. Define a project entry, ownership and verified commands from the actual project sources. Keep project facts outside the Core.
  4. Point the project's AGENTS.md or equivalent tool entry at that project context. Supply the task and follow Task → Project → Framework.

Direct access on this website ​

The public Framework Core is also available as individual, unchanged Markdown files on this website, with relative topic links intact:

Use these files when the agent cannot retrieve GitLab content. The copy contains the Framework Core, its Facility topics and independent examples, not a project context. The copy is AI Context 2.0.0, compatible with JoinedWorkz 1.3.81, and retains the Apache-2.0 license. The canonical source is the AI Context repository.

Demo project context ​

The official JoinedWorkz demo repository uses the same Task → Project → Framework direction. Its AGENTS.md points to the project entry. The project metadata requires only README.md, 09-development-rules.md and 12-ai-usage-instructions.md; the other project documents and relevant Framework topics are read on demand. The matching Framework Core is available locally under ai/joinedworkz-context-core.

The AI Context repository also contains a filled Demo project-context example. That copy contains project knowledge, not the Demo's source tree. Its native source links point to the selected Demo branch; Framework links use the local Core in the AI Context repository. When working on a Demo checkout, start from that checkout's AGENTS.md and current sources. Treat the Demo as one project-specific integration example, not as a mandatory JoinedWorkz structure.

5. Recommended AI workflow ​

Identify the immediate ownership boundary, then use small model/generation probes for open mapping questions. Iterate model changes, generation, inspection of affected outputs and manual integration. A complete repository inventory is not a prerequisite for the first useful change.

First-cut files are intended for manual completion and maintenance, including removal when obsolete; they are not disposable generated output. Preserve accepted versioned history, required generation state and existing relevant tests. Verify the final changed boundaries and report any evidence gaps.

6. Related guidance ​