Jekt™ Design Principles

Last Updated: 2026-06-12

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

"Jekt" is a trademark of GlobalMentor, Inc.

1. Introduction

1.1 Purpose

This document captures the worldview that produced Jekt and the constraints that guide its evolution. It states what Jekt is as an idea, the commitments that follow from that idea, the working principles that operationalize those commitments, the rules under which Jekt should grow, and the directions Jekt explicitly rejects.

This document serves as a touchstone rather than a manual. A reader facing a Jekt design question should be able to consult it and either find a principle that resolves the question or recognize that the question lies in an acknowledged open tension. A reader proposing a change to Jekt should be able to check the proposal against this document and see whether it supports or weakens Jekt's character.

1.2 Status

This is a living document. The principles here represent positions that have emerged and been tested across Jekt's design discussions and field experimentation; they are sharpened and extended as Jekt evolves. Sections marked (provisional) describe positions that are settled in direction but whose exact contour may still shift. Sections marked Open Tension describe known unresolved pulls between principles.

This document is authoritative for design direction. It is not normative for implementation conformance; that role belongs to the Jekt Specification.

1.3 Relationship to Other Jekt Documents

Jekt has four primary documents:

The Specification and Design Principles are the foundational pair. Together they carry the full content of Jekt: every mechanical fact and every motivating worldview. The Primer and User Guide derive entirely from the pair. Every claim the Primer makes about what Jekt is, why it exists, or what makes it different should trace back to a claim in this document or the Specification. If the Primer could not, in principle, be regenerated from the foundational pair alone, that is evidence the pair is incomplete, and the gap belongs here or in the Specification — not in the Primer.

Worldview, identity, and motivation originate in this document. Operational mechanics originate in the Specification. Pedagogy and narration belong in the Primer. Task instructions belong in the User Guide.

1.4 How to Use This Document

This document is meant to support judgment at the point of design. Treat it as:

A touchstone for design decisions. When a question has multiple plausible answers, the principles here should guide the choice.
A check against drift. When an addition feels reasonable in isolation but seems to take Jekt somewhere unfamiliar, the relevant principle or anti-principle should help evaluate it.
A vocabulary for design discussion. Quoting a principle ("this violates surfaced semantics over simple summarization") should be clear enough to move a discussion forward.

A principle that cannot guide a real design decision should be sharpened or removed.

2. Conceptual Frame

This section states the worldview Jekt's design reflects. The principles in §3 and §4 follow from this frame. Read without it, they can look like freestanding stylistic positions; within it, they are consequences of a coherent model.

2.1 Tracking Emerges from Context, Not the Other Way Around

The conventional model of project management treats tracking as primary and context as a byproduct: a ticket exists in a database, and any notes, decisions, or reasoning that arise during the work are appended as comments or stored in adjacent documents. In that model, the tracker remains the system of record, while the surrounding reasoning is captured only incidentally.

Jekt inverts that relationship: context is primary, and tracking emerges from maintaining context that is genuinely useful to the people and LLMs doing the work. A ticket is not a row in a database with attached artifacts; it is the directory in which the artifacts of working on a unit of work naturally live. A status is not a state enforced by a workflow engine; it is a small fact recorded alongside the work, free for teams to interpret loosely or to formalize as they choose.

This inversion is the starting point. Every other commitment in this document follows from it.

2.2 Context is One Spectrum, Not Separate Systems

The context around a unit of work normally lives in systems that look unrelated: the conversation in a chat panel, the approach in a planning note, the work item in a tracker, the accepted change in a commit log. Each looks like a different kind of record kept in a different place.

Jekt treats them as related forms of the same project understanding, arranged along a spectrum of durability. At one end is the live conversation, the most ephemeral and finest-grained; at the other is the durable record left behind once the work is done. Granularity broadly rises with it, fine utterances giving way to coarser synthesis, though the durable end keeps artifacts at every grain: a lone minutes entry and a whole-journey summary are equally permanent. Where a piece of context belongs follows from its role. An insight settles into the minutes as an event in the work's history; the reasoning behind a pivot, durable enough to outlive the chunk that produced it, becomes a design; the approach to the current chunk lives in a plan, ephemeral enough to discard once the work is done. Each is stored where that role makes it useful.

Conventional tracking is built only from the durable end — a ticket, a release, a commit all outlive the work — while the reasoning that produced them is gone when the session closes. Treating conversation and commit history as parts of the same context model makes preservation a matter of drawing useful context toward the durable end before it is lost. That is the bridge Jekt exists to build.

2.3 Layered Summarization Boundaries

The artifacts that compose a Jekt ticket form a hierarchy of natural summarization boundaries:

Project
  └── Tickets
        └── Commits (in Git, not Jekt)
              ↑ summarize code changes
        ↑ summarize coherent units of work
  ↑ summarizes current state

Plans, designs, minutes, and comments sit between the ticket level and the commit level, each summarizing a different dimension of the work at a different durability. A plan summarizes the intent of a chunk of work. A commit summarizes accepted changes. A summary, written near ticket completion, synthesizes the journey.

This differs from RAG. RAG summarizes text into chunks of arbitrary boundaries. Jekt summarizes work into units that humans and LLMs already recognize as meaningful. The summarization boundaries are not invented; they are the boundaries the work already has. The corresponding rejection of treating Jekt as a RAG corpus appears as an anti-principle in §6.2.

2.4 Bring Context to the LLM, Not AI to the Tracker

The conventional move when adding AI to a project management system is to attach an assistant to an existing tracker: a chat interface that queries the database, a summarizer that condenses tickets. The tracker remains the system of record; the AI is a layer on top.

Jekt takes a different approach. The artifacts are designed first to be the substrate an LLM can read, reason over, and curate without translation. Tracking happens in the same files the LLM consumes. There is no separate database, no API surface between the tracker and the AI, no schema-to-prompt mapping. The LLM is not treated as an add-on feature of Jekt; Jekt is a structure designed for collaboration with LLMs, in which tracking is a side effect of maintaining usable context.

2.5 The Artifact Hierarchy Follows the Work

The shape of a Jekt ticket directory — description, minutes, plans, designs, comments, summary, TODOs — is not a UI metaphor or a Jira translation. It emerged from observing what needs to survive between conversations, between chunks of work, between contributors, and between sessions of an LLM whose context window keeps closing. Each artifact answers a distinct question:

Description: what are we doing?
Plans: what is the current approach?
Designs: why is the design what it is?
Minutes: what significant events shifted our understanding?
Comments: what observations were made along the way?
TODOs: what should be done later?
Summary: what was accomplished?

The hierarchy answers the question "what would I need to know to pick this work up from cold?" Proposed additions or rearrangements should be checked against that question.

3. Foundational Commitments

These are the deepest principles. They define what Jekt must preserve as it evolves.

3.1 The file system is the database

Jekt artifacts live as plain files in directories. There is no separate index, no generated cache, no parallel store. The file system is not merely where data is stored — it is the data model. Paths function as queries; directory listings and searchable text are the basic lookup mechanisms.

This commitment rules out several otherwise reasonable solutions: regenerated manifests, derived indexes, SQLite-backed caches. If Jekt needs a generated artifact to remain usable, the feature should be deferred or the data layout should be reconsidered.

3.2 Git-native, not Git-dependent

Jekt is designed around Git as the platform for distribution, history, attribution, and the coordination protocols on which multi-contributor workflows rely. Where Git is in use, identifiers are stable under Git operations, artifact formats produce meaningful diffs and clean merges, distributed coordination uses Git mechanisms (refs, branches, commits) rather than out-of-band services, and authorship comes from Git commit authorship. This commitment shapes everything from filename conventions to the ticket number coordination protocol.

The artifact model itself is defined over a directory containing .jekt/ and remains usable when Git is absent. Operations that require Git — distributed coordination, branch-based work, attribution from commit authors — are unavailable in that mode, not silently approximated. The surface that needs Git acknowledges the need; the rest does not.

3.3 Native tooling first

A user should be able to browse, search, and understand Jekt data using only the tools their IDE already provides: the file picker, the content search, the directory tree. Dedicated Jekt tooling is convenience, not necessity. Plugins enhance the experience; their absence does not break it.

This commitment is the reason filenames carry labels (short Title-Case lexical handles whose conservative character set lets them flow unmodified through filename, URL, shell, and display surfaces), identifiers appear in paths, and references render as bracketed text even without resolution. Jekt should remain understandable from the files themselves, even before specialized tooling is introduced.

3.4 Transparent to LLMs

An LLM reading a .jekt/ directory should comprehend it without translation. No proprietary encoding. No schema documentation required to make sense of a ticket. The same properties that make Jekt artifacts readable by humans make them readable by LLMs: plain text, conventional structure, self-describing names.

This is not the same as "machine-readable." Many machine-readable formats are opaque to LLMs without prior schema knowledge. Jekt artifacts are designed so that a model with no Jekt-specific training can act usefully on them from the file system alone.

3.5 Graceful degradation

If every Jekt tool vanished tomorrow, the data would remain fully usable as plain files. A shell script can walk the structure. A human can browse it with any file manager. An LLM can read it cold. Nothing essential is locked behind tooling.

Any proposed feature should be checked against this commitment. A feature that requires Jekt tooling to keep the data usable compromises graceful degradation.

3.6 Surfaced semantics over simple summarization

Producing a role-bearing artifact — a description, a plan, a design, a minutes entry, a commit message, a summary — surfaces semantics the conversation never made explicit. Participants understand each other tacitly; a developer may know why a change was made without stating it; an assistant may settle implementing decisions it never voices. Writing the artifact draws that understanding into the project record, and the artifact's role gives it a durable, interoperable form that carries to later sessions, other contributors, and the tools and assistants that read it.

Simple summarization — compressing the conversation, or the context window, into a smaller conversation — cannot recover what was never said, and a larger window does not help when the knowledge was never in the window to begin with. Such compression preserves only what was stated; surfacing the stream into typed artifacts produces semantics that were previously implicit. A Jekt summary is itself such an artifact: the commitment is against simple summarization, not against summary.

3.7 File-first over conversation-first

When an LLM produces a substantive artifact, it writes the artifact to a file first and then offers a discussion of it in conversation. That discussion presents the artifact; it is not the artifact's source. Generating an artifact in conversation and transcribing it to a file second risks silent mutation between the two: the file is not a copy but a regeneration from compressed understanding.

Field experience has shown that the friction of "save what we just discussed" produces drift that does not occur when the file is authored directly and the conversation summarizes it.

3.8 The LLM is a Collaborator Through Shared Artifacts

Jekt's structure assumes an LLM participates as a collaborator by producing and consuming artifacts alongside the human contributor. The LLM is not a separate channel that interacts with a tracker on the user's behalf. The LLM reads what the human reads, writes what the human writes, and shares the same artifacts. The shape of those artifacts is designed for both.

4. Design Philosophy

These are the working principles that guide concrete decisions. They follow from the conceptual frame and the foundational commitments. Each shapes specific design choices, and most have excluded plausible alternatives.

4.1 Convention over configuration

Predictable paths and naming patterns eliminate the need for metadata registries, configuration files, and discovery mechanisms. A reader who knows the Jekt convention should be able to construct the path to any artifact without consulting an index. Conversely, a path that requires a lookup table to interpret has lost the value of convention.

Consequence: prescribed filenames (minutes.md, summary.md, description.yaml), the tickets/ and releases/ directories, the tickets/{ticket-id} branch pattern. Configuration files at the project level are introduced only when a genuine project-scoped choice cannot be encoded by convention.

4.2 Open-world semantics

Absence of a property is absence of assertion, not a value. Jekt has no null sentinel, no unknown, no n/a. Defaults are not stored; they are applied at the tool layer when consuming data. Files stay minimal; creating a ticket requires no placeholder metadata.

This avoids the entire class of null-propagation bugs that arise when absence is encoded as a value. It also aligns with how Jekt artifacts actually accrue: a ticket comes into existence with almost nothing recorded, and properties accumulate as they become meaningful.

4.3 Composable context

Context is not loaded wholesale; it is composed. The LLM (or a tool acting on its behalf) selects relevant artifacts based on the task at hand: the plan for the current chunk of work, the minutes when reviewing design decisions, the description when establishing scope. The artifacts are designed to be useful on their own and in combination.

This is why minutes serve as an index to design documents rather than embedding them, why plans are separable from the ticket description, and why each artifact answers a distinct question. Composability depends on keeping those roles distinct.

4.4 Identity by topic versus identity by time

Some artifacts are historical records, ordered chronologically and append-only (minutes, comments). Others are living documents, identified by what they are about and refined over time (design documents, TODOs). Plans sit between the two: their filenames are date-prefixed for chronological positioning within the ticket, but each plan is an iteratively edited working document for the chunk of work it covers. The distinction is reflected in filename conventions: timestamps and dates for chronological artifacts, labels for topical artifacts.

This is not a stylistic choice. Conflating the two — treating a design document as append-only, or a comment as a living document — distorts the artifact's role and makes the repository harder for both humans and LLMs to interpret.

4.5 Locality of metadata

Metadata about a ticket lives with the ticket. Release assignments are recorded in the ticket's own jekt/releases.lst, not in a manifest in the release directory. Tags are in the ticket's tags.lst, not in a project-level index. Status, priority, and assignment are in the ticket's description.yaml.

The release directory holds release-specific content (description, status, release notes) and does not list its tickets. Querying "what tickets are in release 2.0.3?" is a query against the file system, not a lookup in a manifest. Locality keeps merge behavior clean, makes editing self-contained, and avoids orphan data when a ticket is moved or deleted.

As a direct consequence, tickets refer outward only. Inverse relations are not stored. Queries like "what depends on this ticket?" are answered by searching tickets that name it, not by maintaining reciprocal back-references on the targeted ticket.

4.6 Cardinality discipline

Each metadata property has a fixed cardinality declared by the vocabulary. A scalar property is always a scalar; a list property is always a list, including for single values. Polymorphic scalar-or-list forms are not used.

The cost of this discipline is a slight verbosity (tags: [security] rather than tags: security). The benefit is the elimination of an entire class of parser bugs and consistent diffs.

4.7 Lowercase canonical, uppercase representational

Jekt-created machine identifiers — file system paths, Git branches, Git refs — use lowercase by default. Human-facing references in Markdown body content, headings, and commit messages may use uppercase to preserve the visual scannability that Jira-style identifiers established in developer culture. CommonMark's case-insensitive reference-label resolution makes prose links forgiving; Jekt identifiers remain caseful.

The two forms are not interchangeable. Each has a role: mixing them on the file system or stripping uppercase from prose both work against the design.

4.8 Friction in the right places

A TODO is a lightweight note; a ticket is a commitment. The friction of creating each should match its weight. A TODO should be captured without ceremony, in the directory where the work that surfaced it is happening. A ticket should require enough effort to indicate intent to do the work. A design document should be created when reasoning is too complex for a minutes bullet. A minutes entry should be added when an event is significant enough to survive past the conversation.

When the friction of producing an artifact is mismatched, the artifact either stops being produced or accumulates as noise.

4.9 Singletons at the root, collections in subdirectories

A ticket directory's root holds singleton artifacts (description, minutes, summary) and ad-hoc work products (migration guides, reports, analyses). Subdirectories hold collections of Jekt-defined artifact types (plans, designs, comments). This gives the ticket root a stable, scannable shape regardless of how much working context accumulates.

The notable exception is the todo - prefix, which keeps TODOs at the root despite being potentially many. The reason — TODOs are annotations on the ticket, outward-pointing, akin to // TODO in code — is itself an instance of letting the artifact's nature drive the placement decision rather than imposing a uniform rule.

5. Evolution Principles

How Jekt should grow over time without losing its character.

5.1 Local-first, federate by choice

Jekt is complete as a standalone system. It is not a thin client for an external service, and it does not depend on synchronization with any other system. Integration with Jira, GitHub Issues, or any successor is an optional bridge layered over a Jekt repository that works on its own. Adopters own their tracking data locally, in a portable format, and choose whether to federate.

This commitment rules out designs that make federation a required assumption. A feature that only makes sense when a remote service is reachable should live outside the core.

5.2 Backward compatibility through graceful degradation

When Jekt evolves, older repositories should remain usable by newer tools, and newer repositories should remain usable (possibly with reduced fidelity) by older tools. The mechanism is the same as the mechanism for everything else: unknown files are preserved, unknown properties are tolerated, and conventions extend rather than break.

A change that requires migration of existing repositories should be considered carefully. A change that breaks readability of an existing repository in a generic text editor is very unlikely to fit Jekt.

5.3 Minimal core, conservative additions

The set of Jekt-defined artifact types and vocabulary properties should remain small. Each addition raises the floor of what every Jekt user must understand, what every Jekt tool must handle, and what every adjacent system must map. Restraint here has lasting value.

The conservative posture is: prefer an open convention that extensions can occupy over a closed enumeration that excludes them; prefer letting users create ad hoc artifacts at the ticket root over inventing a category for every recurring pattern; prefer fewer mandatory mechanics over more.

5.4 Stable artifacts, evolving understanding

The shape of the artifact hierarchy — description, plans, designs, minutes, comments, TODOs, summary — should be stable. Refinements to how artifacts are produced, what belongs in each, and which are emphasized in which workflows are expected. Refinements to what artifacts exist are not.

A change that introduces a new top-level artifact type changes Jekt's character. Such changes should be rare, well-motivated, and recognized as such.

6. Anti-Principles

This section names what Jekt is not and which design directions are out of scope. It prevents drift by making those boundaries explicit.

6.1 Jekt is not a database with a file-based skin

The file system is not merely Jekt's storage; it is Jekt's data model. Treating the file system as a serialization of a relational or document store, then proposing tools that abstract it away, does not match the design. Browsing the directory tree, reading a Markdown file, and grepping for an identifier are first-class operations, not substitutes for a missing query interface.

6.2 Jekt is not a RAG memory system

RAG systems chunk arbitrary text and retrieve by semantic similarity. Jekt summarizes structured work into artifacts that humans already recognize as meaningful. The two are easily confused because both extend an LLM's effective context, but they operate at different levels: RAG retrieves text; Jekt provides structured working context. A Jekt repository is not a RAG corpus, and a RAG retrieval system is not a substitute for Jekt's artifact hierarchy.

6.3 Jekt is not a tracker with AI bolted on

The defining inversion of the conceptual frame is that Jekt is structure for collaboration with LLMs, with tracking as a side effect. Designs that treat the tracker as primary and the LLM as a layer querying it leave that inversion out. Adding a chat interface to a directory of tickets does not by itself establish the Jekt model.

6.4 Jekt is not a generated-index system

Any proposal that requires regenerating a derived artifact (an index, a manifest, a search cache) to make the system usable contradicts the foundational commitment that the file system is the database. If a tool must keep a generated artifact in sync with the directory contents for the system to function, the system has acquired a sync problem, a tooling dependency, and a corruption vector.

6.5 Jekt is not a live integration target for external trackers

Synchronization with Jira, GitHub Issues, or other systems is an optional bridge over a Jekt repository that exists on its own. A live two-way sync that makes Jekt a thin reflection of an external system contradicts the local-first commitment. Federation by choice must not become federation as dependency.

7. Open Tensions

These tensions are real and acknowledged. Each names a place where principles pull in different directions, identifies the competing principles, and states the current resolution if any. An open tension is not a failure; it is a place where Jekt's design has not yet determined which principle should dominate.

7.1 Discoverability versus determinism in filenames

The pull. Native tooling first and transparent to LLMs both favor filenames that carry the label — description - Auth Token Refresh.md is discoverable in a file picker without opening it, and an LLM searching for **/foo-123* finds the file even outside its directory. Convention over configuration and the desire for deterministic programmatic access favor a fixed filename — description.md is constructible from the ticket ID without prior knowledge.

Current resolution. Provisional in favor of the prefixed-and-labeled form (description - {Label}.md), based on field experience showing that LLMs reach for **/{id}* patterns and humans benefit from label visibility in file pickers. Determinism is preserved through the prefix (description -) and through the companion description.yaml, which is fully prescribed.

7.2 Locality versus visibility for in-progress tickets

The pull. Locality of metadata and the Git-native commitment mean that ticket data lives on the ticket's feature branch and is invisible to teammates until the branch merges. This is correct for the artifact model but produces a visibility gap for managers and team members who want to see what is in progress.

Current resolution. No resolution. The first generation of Jekt deliberately does not address this gap; the ongoing shift toward branchless development and LLM-assisted workflows makes premature design risky. Possible directions (forge-API-based dashboards, dedicated visibility branches, batch-creation rituals) have been considered and deferred.

7.3 Simplicity versus completeness for the metadata vocabulary

The pull. Minimal core, conservative additions favors keeping the Jekt-defined vocabulary small. The need to round-trip with adjacent systems (Jira, GitHub Issues) and the desire to support genuine team workflows pull toward a larger vocabulary that covers more cases out of the box.

Current resolution. Provisional in favor of the minimal core. Properties not currently defined (severity, sprint association, reporter, due dates) are deferred until concrete use cases demonstrate them. Extension properties carry the slack: organizations and external systems can introduce their own properties in namespaces without bloating the Jekt core.

7.4 Plan ephemerality versus design durability

The pull. Convention over configuration and the file-first commitment both favor a single uniform artifact category. The recognition that plans serve a fundamentally different role from designs — ephemeral execution scaffolding versus durable reasoning — pulls toward distinct categories with different lifecycle expectations.

Current resolution. Plans and designs remain distinct: plans in plans/, optionally ignored by Git; designs in designs/, always committed. The friction is in the extraction step: design-quality reasoning often appears first inside a plan and must be promoted to a design document before the plan is discarded. The extraction is currently manual and prone to omission.

7.5 Single project per repository versus multiple project slugs

The pull. Convention over configuration favors the simplest case: one repository, one project slug, one set of conventions. Real workflows — framework-plus-examples spread across components, repository splits, repository merges, importing legacy Jira projects with overlapping IDs — pull toward supporting multiple project slugs in one repository.

Current resolution. Multiple project slugs in one repository are permitted. The flat layout (.jekt/tickets/foo-123/) makes this natural without structural change. Operational questions (which slug should an LLM choose when creating a ticket; how should project-level configuration be scoped) are open.