How the workflow works

The Zekoder workflow keeps a repository's planned work as files inside the repository, in a .zekoder/ folder. Agents read and write those files through the Zekoder MCP server, and the Issues screen shows the same data.

The path from idea to merge

1. Capture. Write down an idea, a bug, a followup, or a decision with a quick command. Nothing is planned yet.
2. Plan. /zekoder-plan turns an item into a plan: it asks you questions, studies the code, writes the plan, and has a reviewer agent check it. You approve the plan before it is committed. The item becomes planned.
3. Implement. /zekoder-implement (or Implement on the Issues screen) hands the plan to a supervisor agent. It splits the work into tasks, runs each task in its own git worktree with a coding agent, reviews and checks each one, and merges the result.
4. Done. The item closes as completed or fixed.

You approve every commit the workflow makes to your main branch: plans before they land, and code through a pull request or a local merge, depending on your merge mode.

Item types

Statuses

Every item has a status and a sub-status, such as open/planned or closed/completed.

Only open/planned features, bugs, and followups can be implemented. Only open/captured ideas can be promoted from the Issues screen.

Light and full plans

/zekoder-plan picks a size for each plan:

• Light: one document and one branch, for changes of about five files or fewer in one area with no new contracts or dependencies. When in doubt, Zekoder recommends light.
• Full: extra investigation agents and a thorough review. A full feature gets its own folder with an overview, a checklist, contracts, external dependencies, and one document per package.

Set Planning tier to Always full in project settings to skip light plans.

The .zekoder/ folder

.zekoder/
  this.md            what the repository is, its rules and quality gates
  kb/                longer reference notes: architecture, conventions, goals, guardrails
  features/          one file per light feature, one folder per full feature
  bugs/
  followups/
  vendor-issues/
  decisions/
  ideas/
  config.json        your workflow settings (not committed)

Commit everything in .zekoder/ except config.json, which holds each developer's own settings and stays out of git.

Set up a repository

You do not create .zekoder/ by hand. The first time you run /zekoder-plan, /zekoder-bug-report, /zekoder-debt, /zekoder-decision, /zekoder-goals, or /zekoder-implement in a repository without it, Zekoder asks to set it up. A first-time agent then:

1. Creates the folders and config.json.
2. Reads the repository and writes this.md and the kb/ notes.
3. Shows you the result and commits it after you approve.

The first /zekoder-plan also asks three one-time questions: the maximum number of packages per feature, the default merge mode, and the simplify mode. You can change them later in project settings.

Run /zekoder-goals to write down the repository's purpose, goals, and guardrails, which planners follow.

/zekoder-idea never sets up a repository. Run one of the commands above first.

Where the workflow runs

The workflow's skills, agents, and MCP server are installed once for your user on each host, not into each repository. Zekoder installs and updates them automatically; see Versions and updates. They work with Claude Code and Codex by default, and with OpenCode and Oh My Pi when you select them.