Import a repo's state

If your project already has history (releases, a changelog, decision records, open issues), you don’t have to retell it to Lea. Minga’s MCP server offers an import prompt: your own Claude Code session reads the repo, drafts the project’s state, shows you the draft, and writes it into Minga when you say go.

An import records history and plans. It never starts work. No milestone goes into Now, and no worker is assigned.

Before you start

• Connect Minga over MCP in the session you will use.
• Create the project in the app (for example “Dictly”), and attach the repo to it.
• Open the session in the repo you want to import. gh helps: with it, the import also reads releases, pull requests and issues.

Run the import

Claude Code

Run the prompt with your project’s id as its argument:

/minga:import_repo_state <project id>

You don’t need to look the id up: an empty project’s Overview shows this command with the id filled in and a copy button, and so does Account › Connected apps when you open it from the project (Connect Claude Code). Claude Code splits a prompt’s arguments on spaces, so the project goes in as one word. A slug (dictly) also works when only one of your projects has it; the id is safe when two of your workspaces have a project with the same slug.

Codex

Codex does not offer MCP prompts. Account › Connected apps, opened from the project, has Copy the import prompt with the project and the date filled in; paste it into a Codex session in the repo. You can also paste the text below, with <project> replaced by your project’s id and <date> by today’s date.

What happens

1. It reads what exists in Minga: the project’s brief and its version, goals, KPIs, areas and items, so it never creates a duplicate.

2. It reads the repo: README, CLAUDE.md or AGENTS.md, docs/ (decision records, specs), the changelog and release notes, TODO and FIXME comments, recent tags, commits and branches, and, if gh works, releases, pull requests and issues.

3. It shows you a draft before writing anything:

   • the brief in its five sections, under 8,000 characters, with the real build, test and release commands;
   • goals (up to five) and KPIs, if there are outcomes to measure;
   • shipped versions as done milestones, oldest first, with the ship date in the title (“2.3 (Oct 1)”) and their main features as done items;
   • the version in progress as a milestone in Next, with a Why / What / Not in this release spec and an item for every requirement;
   • later versions as milestones in Later;
   • ideas nobody has planned, in Later;
   • open questions as question items assigned to you;
   • decisions: the why behind the three to eight biggest past choices, with links to their sources.

4. You review it and say go. Ask for changes first if anything is off.

5. It writes everything in one plan call (split into several if it is over 300 changes, shipped milestones first). If you don’t manage the project, it leaves the brief out and shows you the draft, so the project’s owner can paste it into the brief on the Overview.

6. It posts the decisions as decision comments on the milestones and items they shaped, and records the current KPI values with where each number came from.

7. It reports and hands over to Lea: the refs it created, anything it was unsure about, and a message to Lea that the import is history, not a new plan, asking what is missing and what she would do next.

Everything is written in the session’s own words, with links to the sources. It does not copy passages from issues, pull requests or docs, and it keeps secrets, keys, customer data and personal data out.

Check the result

Open the project’s Overview:

• Brief at the top, with its first revision.
• Milestones: the version in progress in Planning; later ones as Idea.
• Implemented: the shipped versions, newest first.
• Open questions and Decisions filled in.

When the breakdown of the version in progress looks right, move it to Now to start the work.

If a result says items are ready

Items the import created or moved that a worker could start right away are named in a warning. That should not happen with the prompt as written (nothing is put into Now), but if it does, the session tells you at once. Pause or move those items if you did not mean to start them.

The prompt text

Show the import prompt (for Codex, or to read what it does)

Use the minga MCP tools to put the current state of this repo into the Minga project "<project>", so its lead can plan
from it and its Overview shows where it stands. Work in this order and keep it factual. This import records history
and plans; it never starts work.

1. Call list_projects, then read_project for <project> (include done). Note what already exists: the brief
   (`project.brief` and its version `project.briefVersion`), goals, KPIs, areas, items, and `you` (your @handle).
   Never create a duplicate; change or extend what is there instead.
2. Read this repo: README, CLAUDE.md / AGENTS.md, docs/ (decision records, specs), CHANGELOG and release notes, TODO
   and FIXME comments, `git tag --sort=-creatordate | head -30`, `git log --oneline -60`, `git branch -a`, and if gh
   works `gh release list --limit 20`, `gh pr list --state all --limit 30` and `gh issue list --limit 50`. Look at what
   shipped and when, what is half done on branches, what is planned, and why the big choices were made.
3. Draft the import and SHOW IT TO ME before writing anything:
   - Brief: the whole brief in five sections, a few short lines each, under 8,000 characters in all: `## Vision`,
     `## For whom`, `## Principles`, `## Not doing`, `## How to build and test` (the real build, test and release
     commands from this repo). Project-wide choices ("no Android") go into Principles or Not doing. If the brief
     already has text, keep what is still true and show me what changes.
   - Goals (0 to 5): outcomes you can measure, with a target on a KPI and a deadline if one is known. A shipment is
     not a goal: it is a release.
   - KPIs: name, unit, direction, cadence, role (input, lagging or health), source manual. Note the current value
     and where it came from, if you know it.
   - Shipped versions (git tags, CHANGELOG, store versions): each one a top-level `release` with `status: "done"`,
     the ship date in the title ("2.3 (Oct 1)", with the year when it is not this year) and in `statusNote`
     ("Shipped 2026-10-01, tag v2.3.0"), and its main features as done children (one per real feature, not per
     commit). No `dueAt` on them: `dueAt` is a plan, not a ship date. Oldest first. Without tags, one done release
     "Before Minga" holds what shipped.
   - The version in progress: a top-level `release` with `status: "todo"` (Next), `dueAt` if a date is known, its
     goals in `goalIds`, and a spec in `body` with three sections: `## Why` (the problem, and the goal it serves),
     `## What` (the requirements as a plain list), `## Not in this release` (scope cuts). Every What line gets a
     child item (feature, bug, chore or research) with its own spec. Leaves I am working on right now:
     `in_progress`.
   - Later versions: releases with `status: "backlog"`, a short spec in the same sections, and `dueAt` if a date is
     known.
   - Other ongoing work that is not a version: a `workstream` with its children. Never put a task, bug or feature at
     the top level. Every release and workstream goes into an area.
   - Ideas nobody has planned: `idea` items with `status: "backlog"`, under the release they belong to, or at the top
     level.
   - Open questions (not decided yet): a `question` item under the release it affects, with the status of its
     release (`todo` or `backlog`), `assignee` set to `you`, and a `blocks` edge to the item it holds, if any. Do not
     use capture for them.
   - Decisions: the why behind the 3 to 8 biggest past choices (from decision records, docs and PR discussions):
     what was decided, why, and a link to the source. Each one becomes a decision comment on the release, item or
     goal it shaped (step 5). Project-wide choices are in the brief instead.
   - Every item gets a full spec in `body`, in your own words, with references (file paths, PR and issue URLs). Do
     not paste text from issues, PRs or comments; summarize it and link the URL. "Done when" checks only on todo and
     backlog leaves, and only where a command or a person can verify them. Dependencies as `blocks` edges.
   - Status: `done` for what shipped; `cancelled` for what we dropped, with a one-line `statusNote` on why;
     `in_progress` only for leaves I am working on right now (they get assigned to me); `todo` for what is next;
     `backlog` for later.

     Never put a release or any other top-level item into Now (`in_progress`), do not write MoveItem, and do not
     assign workers or agents: moving a release into Now is my approval, and I give it in Minga.
4. After I say go, write it with ONE `plan` call. Put the brief in it as a `ReviseBrief` change: `body` is the whole
   new brief, `baseHash` is `project.briefVersion` from read_project, `why` is "Import from the repo on <date>".
   Include the ReviseBrief only when the new brief text differs from `project.brief`; leave it out when it would be
   identical (an unchanged brief is refused, and one refused change refuses the whole plan). If the plan is refused
   because you may not change the brief (`not_owner`: you don't manage the project), send the same plan again
   without the ReviseBrief and show me the brief draft, so the project's owner can paste it into Settings.
   `dueAt` is in epoch milliseconds. Use $labels for everything new and refs (DIC-12) for what exists.
   Rationale: "Import of <project>'s current state from the repo on <date>, via Claude Code. History, not a new plan."
   If it is over 300 changes, split it: the ReviseBrief and every shipped release (status done) with its children
   come first, oldest first (a release's place in Implemented is the order it closes in), then the rest by area; use
   the refs returned by earlier calls in later ones. If a result warns that items "are ready", tell me at once.
5. Post the decisions: one `comment` per decision with `decision: true`, `target` the ref from step 4, and one or two
   sentences: "<what>. Why: <why>. Source: <link or path>".
6. Record the current KPI values with record_kpi (evidence: where the number came from).
7. Finish with read_project and report the created refs, anything you were unsure about, and any warnings. Then
   ask_lead: "I just imported <project>'s current state from the repo (rationale: history, not a new plan). Don't
   re-plan the imported items. What is missing, and what would you do next?"

Rules: no secrets, tokens, keys, customer data or personal data in the brief, a spec or a comment. Write the brief,
every spec and every decision comment in your own words; never copy passages from the README, store copy, decision
records, issues or PRs; link the source instead. Link files instead of pasting large code. One item per real piece
of work, titles under 80 characters.