Jekt™ Quickstart

What Jekt Is

Jekt keeps a project's working context as plain files in the Git repository: tickets, plans, designs, minutes, summaries, and related material that you, your team, and an AI assistant can read directly. Tracking follows from keeping that context; it is not a separate database or service.

By the end of this Quickstart you will have a .jekt/ directory in your own repository, one real ticket with a small implemented change, a decision recorded in minutes.md, and a local commit whose subject names the ticket.

For the fuller orientation and the ideas behind Jekt, read the Jekt Primer.

Set Up

You need VS Code with GitHub Copilot enabled, Git installed, and a repository where Jekt can write files. Use an existing project if you are ready to try Jekt there, or create a fresh practice repository if you want a low-stakes first run.

For an existing project, open the repository folder in VS Code. If the repository already has at least one commit, you do not need any repository-prep commands.

For a fresh practice repository, create the repository and make an initial commit before starting the Jekt walkthrough:

mkdir jekt-practice
cd jekt-practice
git init
echo "# Jekt Practice" > readme.md
git add readme.md
git commit -m "Create practice repository"

That first commit matters because /jekt-ticket-start later creates the ticket branch from an existing branch. /jekt-init can create local .jekt/ files without Git, but this Quickstart walks through the complete branch-and-commit loop, so start from a Git repository with a commit.

The VS Code extension is coming and will become the preferred way to use Jekt. Until then, install the reference prompts:

  1. Open Reference Prompts.
  2. Save the ambient instruction into .github/instructions/.
  3. Save each command prompt into .github/prompts/.
  4. Open GitHub Copilot Chat.

With the repository-local installation path, your repository has these prompt folders:

.github/
├── instructions/
└── prompts/

The Reference Prompts page has the actual files, copy buttons, and full installation details. After the prompts are installed, continue here with your first Jekt ticket.

Walk Through Your First Ticket

Use the instructions in each step for your own repository. The Bill Splitter snippets show one concrete run-through: a ticket is created, a plan is written, the change is implemented, minutes capture the decision, and everything is committed.

1. Initialize Jekt

In your repository, ask /jekt-init to initialize Jekt with your project name and a short project slug.

Example:

/jekt-init the "Bill Splitter" project with slug "bills"

/jekt-init initializes Jekt for the repository. In the Bill Splitter example, it creates .jekt/readme.md and the project declaration under .jekt/projects/bills/. If the repository has an origin remote, it will also create the remote jekt management branch after disclosing that action, unless you opt out. Initialization is setup only: it does not create a ticket, stage files, or commit.

.jekt/
├── readme.md
└── projects/
    └── bills/
        └── description - Bill Splitter.md

2. Create the First Ticket

In your repository, ask /jekt-ticket-create to describe one real unit of work in plain language.

Example:

/jekt-ticket-create split a restaurant bill evenly among diners

/jekt-ticket-create creates the ticket directory and writes the description. For a new project slug, the first ticket is numbered 1, so the Bill Splitter example creates bills-1. If team coordination is enabled via the management branch, Jekt may reserve that number on the remote before creating the local ticket directory. Creation leaves the new files in your working tree; it does not create a branch or mark the ticket started. The next step makes the ticket the active work context.

.jekt/
└── tickets/
    └── bills-1/
        └── description - Bill Splitting.md

3. Start Work

In your repository, start the ticket ID that /jekt-ticket-create reported. The uppercase display form BILLS-1 is fine, as is the Markdown reference form [BILLS-1]. If the just-created ticket is clear from the conversation, the assistant can usually infer the ID as well.

Example:

/jekt-ticket-start BILLS-1

/jekt-ticket-start requires Git because it creates and switches to the branch tickets/bills-1. It also records that work has started by writing jekt/status: started in description.yaml.

.jekt/
└── tickets/
    └── bills-1/
        ├── description - Bill Splitting.md
        └── description.yaml        # jekt/status: started

4. Plan and Implement the Change

Now do a small piece of real work with the assistant. If the change is more than tiny, ask Jekt to write the execution plan first.

/jekt-plan-create

/jekt-plan-create writes a plan under the active ticket. In the Bill Splitter example, the planning discussion settles one product rule: when a bill does not divide evenly into whole cents, leftover cents go to the first diner so the collected total still matches the bill.

.jekt/
└── tickets/
    └── bills-1/
        └── plans/
            └── 2026-06-09-bill-splitting.md

If the discussion changes direction, use /jekt-plan-update to refine the plan. When the plan is ready, ask Jekt to implement it:

/jekt-plan-implement

/jekt-plan-implement reads the plan and edits your normal project files. For the Bill Splitter example, the assistant implements the bill-splitting calculation using the leftover-cent rule from the plan. The plan stays as the contract for the work; if implementation shows the plan is wrong or incomplete, Jekt stops and asks you to update the plan instead of silently changing direction.

Implementation itself does not create another Jekt artifact. The result appears in your project's own files and Git diff. This walkthrough does not show the plan body or application code; the Primer covers the fuller plan and design lifecycle.

5. Capture Significant Context

At a natural breakpoint, ask Jekt to update the minutes.

/jekt-minutes-update

/jekt-minutes-update looks back over significant events since the last minutes entry and appends what qualifies. It may add several entries, one entry, or none. Use it at breakpoints rather than after every exchange; the prompt curates the entries instead of recording dictated text.

Example minutes entry:

- 2026-06-09 **Decision**: Leftover cents from an uneven split are assigned to the first diner rather than rounded away, so the collected total always matches the bill.

.jekt/
└── tickets/
    └── bills-1/
        ├── description - Bill Splitting.md
        ├── description.yaml
        ├── plans/
        │   └── 2026-06-09-bill-splitting.md
        └── minutes.md

6. Stage and Commit

Stage the files you want in this commit with Git. Then ask /jekt-commit.

/jekt-commit

/jekt-commit reads the staged content, composes a commit message, and creates a local commit whose subject names the ticket. It does not stage files for you, and it does not push. This boundary is deliberate: you choose the commit contents with Git first, and pushing, opening a pull request, or merging stays in your normal workflow.

Example commit subject:

[BILLS-1] Split a restaurant bill evenly among diners

This walkthrough stops at the first commit. To finish or close the ticket, see the FAQ entry on finishing or closing a ticket.

See What You Made

Open the ticket directory that /jekt-ticket-create reported and look at the files Jekt produced. Read the description, plan, and minutes.md in particular. For a brand-new project slug, that directory is usually .jekt/tickets/{your-slug}-1/.

The Bill Splitter example ends with a ticket directory like this:

.jekt/
└── tickets/
    └── bills-1/
        ├── description - Bill Splitting.md
        ├── description.yaml
        ├── plans/
        │   └── 2026-06-09-bill-splitting.md
        └── minutes.md

These are ordinary files in ordinary commits, alongside the project files changed by implementation. A later assistant session can read the ticket artifacts after this conversation is gone, so the reasoning outlives the chat that produced it.

Where to Go Next