Core concepts

Tekk uses a small, deliberate vocabulary. Getting these six words straight makes everything else in the product read clearly.

Workspace

A workspace is your account’s home for a body of work — its board, goals, documents, connected tools, and settings. Access is per-workspace: an MCP API key is scoped to exactly one workspace, and everything Tekk does happens inside one.

Project

A project is a codebase inside a workspace, connected to a Git repository. Loops read and reason about the project’s actual code, so proposals are grounded in what’s really there rather than in guesses. A workspace can hold more than one project.

Spec

A spec is the unit of work — the Tekk equivalent of a task, issue, or ticket, but written to be executable. A good spec is short and structured: what to build, why, and the acceptance criteria that say when it’s done. Specs live on the board and move through states (todo → in-progress → completed).

We say spec, never “task” or “ticket.” The word is deliberate: a spec is meant to be precise enough that an agent — or a teammate — can act on it without a meeting.

Specs come with a type so the board stays legible: feature, problem, technical, research, or improvement.

Goal

A goal is the direction you set for a workspace — the thing you’re currently trying to move. Goals are how you tell Tekk what “better” means right now. The loops orient their attention around active goals, so setting a sharp goal is the main steering wheel you have.

Proposal

A proposal is a suggestion Tekk brings to you on its own — something a loop noticed and thinks is worth doing. You read it, then accept, revise or reject it:

• Accept → Tekk turns the proposal into a drafted spec on your board.
• Revise → you say what to change, and Tekk rewrites the same proposal in place, checking its evidence against your current code again. Use it when the finding is right but the fix or the citations are not. A proposal can be revised up to three times.
• Reject → the proposal goes away, and the reason you give steers future proposals away from that kind of thing.

Loop

A loop is an autonomous routine that runs on your project to find and propose improvements. Different loops watch for different things (a goal to push forward, a performance signal, an error spike from a connected tool). When a loop has something worth your attention, it produces a proposal.

Loops are where the “self-improving” part comes from — they’re covered in depth in How the loops work.