Jekt™ Primer

Last Updated: 2026-11-09

This work is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).

"Jekt" and the Jekt logo are trademarks of GlobalMentor, Inc.

Jekt is a context architecture for software projects. It keeps the working context of a project in the repository itself: tickets, plans, design documents, minutes, comments, summaries, and related material, all as ordinary files under a .jekt/ directory. A developer can browse those files in an editor. An AI assistant can read and update the same files. Git carries the context with the code.

The central idea is that project tracking can emerge from preserving useful context. Traditional trackers start with work items in a database and leave much of the reasoning around them in comments, chat, or nowhere. Jekt starts with the material needed to do and resume the work: what is being changed, what plan is current, which decisions mattered, which alternatives were rejected, and what was learned along the way. Once that context is organized, tickets and releases follow naturally.

Why Jekt Exists

Modern software work produces more than code. A design discussion settles ambiguities. A plan decides the order of change. A test failure reveals that the model was wrong. A constraint explains why the final implementation looks awkward from the outside.

In ordinary development, much of that knowledge disappears. It may remain in a chat transcript, in a local note, in an issue comment that nobody reads, or only in the memory of the person who did the work. In AI-assisted development the problem is sharper: the assistant that helped reason through the work may lose the conversation when the session ends or the context is summarized.

Jekt gives that knowledge a stable home beside the code. The record is not a transcript of everything that happened. It is a curated set of artifacts: the ticket description, the plan used for a chunk of work, the design document that explains a lasting choice, the minutes entries that capture the decisions and pivots worth remembering, and the summary that closes the loop.

What a Jekt Repository Contains

A Jekt repository has a .jekt/ directory at its root. The top-level structure is small:

projects/ declares project slugs, the short prefixes used in ticket identifiers.
tickets/ contains the work units, such as recipe-1 or auth-42.
releases/ contains delivery groupings.

Tickets are the center of everyday work. A ticket directory represents one unit of work and collects the artifacts that belong to it. The main artifacts are:

Description: the ticket's scope and intent.
Plan: the current execution reference for a chunk of implementation work.
Design: durable reasoning about why the system is shaped as it is.
Minutes: significant decisions, pivots, findings, insights, lessons, and milestones.
Comment: a timestamped observation or discussion entry.
TODO: low-ceremony capture of deferred work and what is understood about it so far.
Summary: the retrospective synthesis produced near completion.

The files are ordinary Markdown, YAML, and plain-text list files. There is no hidden service behind them and no generated index that must be kept in sync. Paths and filenames are part of the model: a ticket lives under .jekt/tickets/{id}/, designs live under designs/, plans under plans/, and so on.

A small repository might look like this after a ticket has been planned and implemented:

.jekt/
├── readme.md
├── projects/
│   └── recipe/
│       └── description - Recipe App.md
├── tickets/
│   └── recipe-1/
│       ├── description - Ingredient Scaling.md
│       ├── description.yaml
│       ├── minutes.md
│       ├── summary.md
│       ├── plans/
│       │   └── 2026-05-18-quantity-scaling.md
│       ├── designs/
│       │   └── Quantity Model.md
│       └── comments/
│           └── 2026-05-19T14-30-00Z.md
└── releases/
    └── 1.2.0/
        └── description - Spring Update.md

Not every ticket has every file. A simple ticket may begin with only a description and gain a summary near completion. A difficult ticket may accumulate several plans, designs, comments, TODOs, and minutes entries. Jekt keeps the structure predictable without requiring empty placeholders.

Design Principles

Several principles explain why Jekt has this shape.

The file system is the database. Jekt data is not stored in a remote tracker and exported into files. The files are the data. Opening a directory lists the work, searching text queries it, and a Git diff shows how it changed.

Surfaced semantics over simple summarization. Writing a plan, a design, a minutes entry, or a summary makes explicit the understanding and decisions behind the work — things the conversation itself often leaves unsaid. Producing the artifact is the point at which that knowledge is promoted into the durable project record, where simply summarizing the conversation would lose it.

Native tooling first. Jekt should make sense in the tools developers already use. The repository tree, file picker, text search, Markdown preview, and Git history are all useful without a special application.

Graceful degradation. If Jekt-specific tooling disappeared, the data would remain usable. A developer could read the files by hand. A script could walk the directories. An AI assistant could load the artifacts directly.

The assistant is a collaborator. Jekt is designed so that a developer and an AI assistant work from the same artifacts. The assistant reads the ticket, writes the plan, updates minutes when asked, and helps summarize the result. The files remain understandable to both.

Working With Jekt Today

Jekt can be used today through the Jekt agent skill, which teaches an AI assistant that supports agent skills how to work with Jekt. With it, a developer can initialize a repository, create and start tickets, write and update plans, assess and implement plans, update minutes, commit work, and summarize tickets. A VS Code extension is also available.

The walkthrough below shows what the developer asks for, in plain language. A request can be as short as "Implement the plan", can state a decision for the assistant to record, or can name several activities at once; the wording is the developer's own. Jekt defines the artifacts and their roles, and any tool, or a careful human editor, can produce the same files.

A Ticket in Practice

Suppose a recipe application needs a new feature: when the cook changes the number of servings, the recipe should scale its ingredient quantities.

The developer first enables Jekt for the repository and declares the project slug that will prefix ticket identifiers:

Developer: Initialize Jekt for the Recipe App project, with the slug "recipe".

Initialization creates .jekt/, writes a short orientation readme, and declares the project under .jekt/projects/recipe/. When the repository has the required Git and remote setup, it also creates the management branch used for coordinated ticket-number allocation unless the developer opts out.

The developer then creates the ticket:

Developer: Create a ticket to scale ingredient quantities when the cook changes the number of servings.

Ticket creation reads the project context, chooses the next ticket number for the recipe slug, and writes a description. In a new project, the first ticket is recipe-1:

# [recipe-1] Ingredient Scaling

## Objective

The recipe application scales ingredient quantities when the cook changes the serving count.

## Acceptance Criteria

- Ingredient amounts adjust proportionally when the serving count changes.
- Counted ingredients such as eggs are handled without asking for impossible fractional counts.
- Displayed quantities use forms a cook can read naturally.

The description records the end state, not the implementation steps. When the developer is ready to work, starting the ticket makes it the active work context:

Developer: Start work on recipe-1.

Starting the ticket switches to, or creates, the Git branch tickets/recipe-1, sets the ticket status to started when appropriate, and loads the ticket's existing context for the work session.

The developer and assistant then discuss how ingredient quantities should be modeled and displayed. The result of that planning conversation is written directly to a plan file:

Developer: Show scaled amounts the way a cook would say them, like 1½ cups, since they're read while cooking. Create a plan, then update the minutes.

A plan is not a chat summary. It is the execution reference for the work. A shortened excerpt might look like this:

# [recipe-1] Plan: Quantity Scaling

## Overview

- Represent each ingredient quantity as an amount, a unit, and a scaling behavior.
- Scale continuous quantities proportionally.
- Use nearest-whole rounding as the initial rule for counted ingredients.
- Verify how counted ingredients behave when scaling below one whole ingredient.
- Format scaled quantities for recipe display.

## Open Questions and Assumptions

- Nearest-whole rounding for counted ingredients may still be wrong for small scaled amounts.

The full plan contains the step bodies the implementer will follow. If the planning conversation produces design reasoning that should last beyond this one plan, the assistant writes or updates a design document as part of the same operation. For this ticket, the design might be designs/Quantity Model.md:

# [recipe-1] Design: Quantity Model

An ingredient quantity combines an amount, a unit, and a scaling behavior. Flour and milk scale continuously. Eggs and other counted ingredients scale as counts and need an explicit rounding rule.

The developer continues the planning conversation. Before implementation, the plan can be assessed against the actual code and the ticket's stated end state:

Developer: Assess the plan.

Assessment is read-only. It may say the plan is ready to implement, or it may surface gaps, risks, or assumptions the planning conversation missed. In this example, assessment catches the unsettled counted-ingredient rule: nearest-whole rounding can turn a small sub-whole amount into zero counted ingredients, leaving the cook short.

The developer asks the assistant to revise the plan rather than leaving that finding only in chat:

Developer: Round counted ingredients up instead, so the cook is never left short. Update the plan and the minutes.

The update changes the plan: the round-up rule replaces nearest-whole rounding, which is recorded as a rejected alternative because it can undercount. If that change refines durable reasoning about the quantity model, the Quantity Model design may be updated as part of the same operation. The persisted plan now carries the rule that implementation will follow.

Each minutes update looks back over the significant events since the last minutes entry. It may append several entries, one entry, or none; it does not add a bullet after every exchange. Its job is to preserve what a future reader would otherwise have to rediscover. Updated with the plan and again with its revision, the minutes now read:

# [recipe-1] Minutes

<!-- Categories: Pivot | Insight | Decision | Finding | Lesson | Milestone | Open | Resolved -->

- 2026-05-18 **Decision**: Display scaled amounts in cooking-friendly forms rather than raw decimal output, because the result is meant to be read while cooking.
- 2026-05-18 **Insight**: A quantity is not just a number; it combines an amount, a unit, and a scaling behavior. Flour scales continuously, while eggs are counted. See [Quantity Model](<designs/Quantity Model.md>).
- 2026-05-20 **Pivot**: Counted ingredients now round up instead of using nearest-whole rounding. Nearest-whole rounding could leave the cook short when a small sub-whole amount rounded to zero.

The minutes give the timeline. The design gives the durable explanation. The plan records the execution path. The code records the accepted implementation. These are related artifacts, not competing places for the same content.

Planning may repeat through discussion, assessment, and update until the plan is ready. Then implementation begins:

Developer: Implement the plan.

The plan is read-only during implementation. Implementation itself does not create another Jekt artifact; the assistant edits the project's own files, visible in the Git diff, and reports what was completed, what was skipped, and whether implementation surfaced any divergence. If implementation does reveal that the plan missed something important, the assistant stops and surfaces the issue rather than silently changing direction. In that case, the work returns to planning; additional or later work can also produce additional plans on the same ticket.

After implementation, the developer commits the code together with the Jekt artifacts that belong with it:

Developer: Stage and commit everything.

The assistant reads the staged diff and the ticket context, then creates a normal Git commit whose subject names the ticket:

[recipe-1] Scale ingredient quantities by serving count

Near completion, the developer summarizes the ticket and resolves it:

Developer: Summarize the ticket, mark it resolved, then stage and commit everything.

The summary is a synthesis for later readers. It draws on the description, minutes, designs, plans, comments, and commit history:

# [recipe-1] Summary

Ingredient scaling was added for recipe serving changes. Continuous ingredients scale proportionally, while counted ingredients round up so the scaled recipe does not ask for less than it needs. The quantity model separates amount, unit, and scaling behavior, with the counted-ingredient rule recorded in the Quantity Model design.

Marking the ticket resolved sets its status to resolved and its resolution to completed in description.yaml.

Weeks later, someone asks why the application rounds eggs up in a scaled recipe. The original conversation is gone. The assistant has no memory of it. The answer is still in the repository: the minutes record the pivot, and the linked design explains the model. A developer can open the files directly, or ask the assistant:

Developer: Why does the app round eggs up when scaling a recipe?

No command or ticket ID is needed, because the reasoning is in the repository; what matters is that it outlived the conversation that produced it.

Comparisons

Issue trackers. An issue tracker stores work items in a database. Reasoning usually lands in comments, if it is recorded at all. Jekt makes the reasoning part of the project state: plans, designs, minutes, and summaries are first-class artifacts, and the tracking view follows from them.

Documentation systems. A documentation system stores durable knowledge, but often apart from the work that produced it. Jekt keeps durable knowledge next to the ticket and the code. The record is written where the work is happening.

RAG and memory systems. A retrieval system breaks text into chunks and retrieves by similarity. Jekt stores work in artifacts that already have meaning: a ticket, a plan, a design, a minutes entry, a summary. The boundary comes from the work, not from a text-splitting algorithm.

AI features on trackers. A common approach adds an assistant on top of an existing tracker. The tracker remains the system of record, and the assistant queries it through an interface. Jekt reverses that direction. The files are shaped so the assistant and the developer can read and curate the same project context directly.