ideakit

name	ideakit
description	Think an idea through across many sessions, with one ideas repo holding a folder per idea, a jotpad for the thoughts that have none, one idea open at a time, and nothing written to disk until you ask for it. Use when the user says "capture this idea", "I just had an idea", "jot this down", "random thought", "promote that jot", "let's think about the <X> idea", "brainstorm <X> with me", "what was I thinking about <X>", "where do my ideas stand", "what should I think about next", or names their ideas repo or runs "/ideakit".
license	MIT
disable-model-invocation	true
allowed-tools	Read, Write, Edit, Glob, Bash, AskUserQuestion, WebSearch, WebFetch
metadata	{"internal":false}

ideakit

Keep one ideas repo, one folder per idea, and think about exactly one of them at a time. ideakit captures an idea the moment it arrives, runs the discussion sessions, reports where every idea stands, dispatches the research and validation work to the kits that own it, and folds an answer back into that idea's own log when the user asks to keep it.

An idea is a subject someone wants to think about, not a project they have committed to building. Some ideas become products. Most stay notes, and that is the design.

A jot is smaller again: a thought with no folder, no slug, and no commitment. The jotpad takes any subject at any time, and a jot earns a folder by coming back.

Eight modes. jot drops a loose thought into the pad. promote turns a jot that keeps returning into its own idea. capture writes an idea down and stops. session is the mode that thinks. status reports and writes nothing. research and validate send a question out and bring the answer back. close records a verdict.

jot, promote, capture, and close write on their own. Every other mode offers its writes and takes no for an answer. See Saving is a demand, not a default.

Mode selection

Resolve on intent, not on phrasing.

• "Jot this down", "random thought", "add this to the jotpad" get jot. It records and stops.
• "Promote that jot", "this one deserves a folder", "make j-042 an idea" get promote.
• "I have an idea", "capture this", "write this down" get capture. It records and stops.
• "Let's think about X", "brainstorm X", "pick up the X idea" get session.
• "Where do my ideas stand", "what should I think about next", "where was I on X" get status.
• "Who else builds this", "which library would this need", "what does this category cost" get research.
• "Is this a business", "would anyone pay for this", "should I build this" get validate.
• "I'm dropping this", "I'm building this", "park this one" get close.

An ask that wants a picture or wants to think, but names no idea, is status or session, never a guess between them. status reports every idea; session asks which one to open. When the ask wants a picture, run status. When the ask wants to think, run session and ask for the idea.

When the ask is genuinely ambiguous between capture and session, run capture first. A captured idea can always get a session next; a session on an unrecorded idea leaves nothing behind.

When the ask is genuinely ambiguous between capture and jot, run jot. A jot costs no folder and no permanent slug, and promote upgrades it the moment it earns one. The word "idea" is the discriminator: a user who calls the thought an idea gets capture.

The ideas repo

All state lives in one repo outside the user's work repos, at ~/ideas unless $IDEAKIT_HOME names somewhere else.

~/ideas/                            ← one git repo; $IDEAKIT_HOME overrides
  INDEX.md                          ← the router
  jotpad/
    INDEX.md                        ← the jot router
    YYYY-MM-DD.md                   ← that day's jots, written once
  topics/<slug>/
    IDEA.md                         ← a stable head plus an ## Open block
    NOTES.md                        ← the dated log, append-only
    SOURCES.md                      ← collected links, created lazily
    docs/plans/                     ← a plan skill writes here
    docs/research/                  ← research answers, kept on request
    docs/validation/                ← validation write-ups, kept on request
    docs/sessions/                  ← full session records, on request only
    docs/adr/                       ← decision records
    assets/                         ← diagrams and screenshots

Resolve $IDEAKIT_HOME first and write absolute paths. No mode changes the working directory. A mode fired from a work repo touches no file in that repo, so the host repo's own conventions never apply to what ideakit writes. That is what lets an idea arriving mid-task go straight into the ideas repo.

Create the repo on first use and run git init in it. Never commit automatically. Offer a commit at the end of a session and take no for an answer.

The router

INDEX.md carries one row per idea, with aliases, so a loose ask routes without opening anything:

| Idea | Slug | Also called | Summary | Open question | Status | Last touched |
|------|------|-------------|---------|---------------|--------|--------------|
| Agent memory substrate | `agent-memory` | memory layer, agent recall, context store | A shared store an agent writes facts to and reads back across sessions | Does retrieval beat a bigger window | active | 2026-08-19 |

Status is active, building, parked, or closed. building means implementation runs in another repo, and its cell carries that repo: `building` · owner/repo. parked means the user stopped. closed means a verdict is written in that idea's NOTES.md.

The router cell bound: Summary and Open question are one line each. Each states what the idea is and what is open. Neither carries a reason, a position, or a half-formed argument. A Markdown table gets read whole, so the isolation guard below cannot be kept by reading the router selectively; it is kept by bounding what the router is allowed to hold. Ten ideas then cost ten lines to route and nothing to contaminate.

Read one idea folder, never two

This is the load-bearing rule. Read INDEX.md. Resolve the ask to exactly one slug. Then read only topics/<slug>/. Never glob across topics/, and never grep the repo for context. Listing topics/ is fine, because listing a directory is not reading it.

Two reasons hold it up. Ideas contaminate each other: half-formed thinking about one subject bleeds into the next when both sit in the same window, and the second idea inherits the first one's framing without anyone noticing. And the cost grows the wrong way, because thirty ideas cost about thirty router lines to route and tens of thousands of tokens to open.

One bounded exception. Open a second topic folder only when the user names that idea in the ask ("does this connect to the agent memory idea?"). That folder is read-only for the session, and the connection is written into the primary idea's NOTES.md alone. One session, one owner of the log. When a link looks obvious and the user has not asked, say the link in one sentence and leave the folder shut.

The rule holds across the pad in both directions. A topic mode opens no file under jotpad/, and a jotpad mode opens no folder under topics/. See The jotpad for how a jot session bounds its own reads, and promote for the one mode that touches both.

The three topic files

IDEA.md is the living statement, in two parts. The head says what the idea is, who it is for, and what has to be true for it to matter. An ## Open block below it lists the open questions and the possible next moves.

Rewrite the head when a session changed what the idea is. Draft a refreshed ## Open block every session without exception, and save it with the entry it matches. That split gives a checkable bound: the ## Open block matches the last NOTES.md entry. It also stops an inconclusive session churning the head for no change.

NOTES.md is the log, and it is append-only. One ## YYYY-MM-DD heading per saved session, recording what was decided, what was rejected and why, and the open question the session stopped on. Leave earlier entries alone; a change of mind gets a new dated entry. The log is the record and IDEA.md is a cache of it, so rewrite IDEA.md from NOTES.md when the two disagree.

SOURCES.md collects links, one row per link with the date read and one line on what it settles. Create it on first use, not at capture. Check it before searching.

The jotpad

jotpad/ holds a thought that has no folder. Any subject, no slug, no commitment. A folder is a commitment, and most thoughts do not deserve one on the night they arrive. The pad is where they wait.

jotpad/INDEX.md is the jot router, one row per jot:

| Jot | Id | Summary | Entries | State |
|-----|----|---------|---------|-------|
| Cheap OCR for receipts | `j-042` | A phone photo of a receipt turned into a line-item table, run locally | 2026-08-24, 2026-09-02 | live |

State is live, promoted, or dropped. A promoted cell carries the slug it became: `promoted` · `agent-memory`. A dropped row stays, so the same thought does not come back as a new jot. The Summary cell is one line and carries the same bound as the idea router, because this table also gets read whole.

jotpad/YYYY-MM-DD.md holds that day's jots, one block each:

## j-042 · Cheap OCR for receipts

Two to six lines in the user's own words: what the thought is, and what set it off.

A dated file is written once and never edited again. Every state change lands in jotpad/INDEX.md instead. The pad then has one place to look and one place to repair, and the date a thought arrived survives everything that happens to it afterwards.

An id is permanent and never reused. Allocate it by reading jotpad/INDEX.md, taking the highest id, and adding one. A jot the user returns to gets a second block under the same id in the new day's file, and its row gains that date. Three entries is the promotion signal, because the user has now come back twice and that is what a folder is for.

Dropping a jot is a one-cell edit. When the user says a jot is nothing, set its state to dropped and write nothing else. It needs no mode and no verdict entry: a jot never claimed enough to need one.

The isolation guard covers the pad. A jot run reads jotpad/INDEX.md and INDEX.md, both bounded routers. A jot discussion reads those plus only the dated files that one jot's row names. Neither opens a folder under topics/, and no topic mode opens a file under jotpad/. promote is the single crossing, and it reads one jot and writes one topic folder.

A dated file does hold unrelated jots side by side, so reading one thread carries its neighbours into the window. That cost is accepted and it is bounded. The pad holds loose thoughts by definition, and a thread heavy enough to be worth protecting from them is a thread that has earned promote.

The router is a cache, so repair it

Repair runs at two levels, and each mode repairs only what it can see.

• Offer a topic's router row rewrite whenever a mode has that folder open and changed it, in the same save offer as the entry that changed it. capture and close write their row without asking.
• Report an unregistered folder rather than opening it. A folder missing from the router needs five fields that live inside it, and reading it would break the guard for a bookkeeping errand. So status names the folder and says to run session on it to register it.
• Repair the jot router without asking. Its cells hold an id, entry dates, and a state, which is bookkeeping rather than thinking. A jot's row is the only record of that jot's state, so it is written whenever a mode changes one.

The slug is permanent

A slug is short, lowercase, kebab-case, and taken from the idea's core noun. capture proposes it and confirms it with the user before creating anything, because no mode renames a folder afterwards. The cost lands once at creation instead of in rename machinery for a rare event. The router's Idea column carries the current human name and stays free to change.

Artifacts land inside the topic folder

The artifact root is the topic folder, not the repo root. A skill that documents a path under docs/ writes it under topics/<slug>/docs/ instead, keeping its own subpath and filename convention intact. docs/plans/plan-sso-2026-07-23.md becomes topics/<slug>/docs/plans/plan-sso-2026-07-23.md.

This is a root swap, so it holds for every skill, including one added after this file was written. The repo root has no docs/ directory and does not gain one.

Filenames follow <type>-<slug>-YYYY-MM-DD.md, with the artifact's creation date at the end. Keep that date stable when the file is edited later.

Saving is a demand, not a default

The discussion is the deliverable. A file is what the user asks for when the discussion earned one. Most sessions explore and stop there, and a repo of entries nobody wanted is worse than a thin one, because a later status run reads every row as something the user meant.

So every write runs through one gate:

1. Compose the write anyway. Draft the NOTES.md entry, the ## Open block, and the router row in full.
2. Print the draft as a code block, under the absolute path it would land at.
3. Ask save, edit, or drop. Take a no for an answer, and write nothing.

Composing first is what makes the yes cheap. An offer that asks "want me to save this?" with nothing attached gets declined for the wrong reason.

The gate covers every file, the router row included. INDEX.md holds a summary and an open question, which are thinking rather than bookkeeping, so the row goes with the entry it describes. A session the user did not save did not touch the idea, so Last touched stays where it was.

jot, promote, capture, and close are exempt, because in each the ask is the write. "Jot this down", "give that one a folder", "write this down", and "I'm dropping this" are demands already made, and the file is the whole output of the mode. Turning one into an offer asks the user to confirm the thing they just requested. promote still confirms the slug before it creates anything, which is a different question: not whether to write, but under what permanent name.

The user can say "save that" at any point. Write the entry then, and carry on. Offer a save unprompted only once mid-session, when the discussion settles something that would cost real work to reconstruct.

The cost, stated plainly. session opens on a status report, and status crowns the coldest idea carrying an open question. Both read NOTES.md. Unsaved sessions leave those reads behind what the user actually thinks. The hand-off says so on every run that writes nothing, so a thin log never passes for a quiet month.

Mode: jot

Drop the thought into the pad and stop. It does not discuss, does not propose a slug, and does not create a folder. See The jotpad for the file formats.

1. Read the two routers, and nothing else

Read jotpad/INDEX.md. Match the thought against every jot summary. When one is plainly the same thought, append a block under that jot's existing id. Otherwise allocate the next id.

Read INDEX.md too, because it is bounded and cheap. When the thought plainly belongs to a registered idea, say so in one line and write the jot anyway. The pad is the low-friction door, and stopping to route a thought is the friction the pad removes. promote is what moves it later, and it appends to that idea rather than creating a second one.

Open no topic folder and no dated file the matched jot does not name.

2. Write the block

Create jotpad/YYYY-MM-DD.md when today has no file yet. Append the block under a ## j-NNN · <short title> heading, two to six lines in the user's own words. When the mode fires from another repo, record that repo in the block. Where a thought arrived from is usually part of the thought.

Leave every earlier block in the file alone.

3. Write the jot router row

On a new jot, add the row: the title, the id, a one-line summary, today's date, and state live. On a return, add today's date to the existing row's Entries cell and leave the rest of the row as it is.

Done when the block exists in today's file and jotpad/INDEX.md names it. Then go to Hand off.

Mode: promote

Turn a jot into an idea. This is capture with a source, and it is the one mode that reads the pad and writes a topic folder.

1. Route to exactly one jot

Read jotpad/INDEX.md and resolve one id. With no jot named, ask. Offer the live jots, the ones with three or more entries first, and use AskUserQuestion when four or fewer fit. Then read only the dated files that jot's row names.

2. Match against the idea router

Read INDEX.md. Match the jot against every slug, every alias, and every summary, as capture does. When anything is close, show the candidate row and ask whether this appends to that idea or starts a new one.

3. Confirm the slug, then create

On a new idea, propose a slug and confirm it before writing anything, because it is permanent. Then create topics/<slug>/, write IDEA.md from the jot's own blocks, and write the first dated NOTES.md entry. That entry names the jot id and the date the thought first arrived, so the folder carries its own origin.

On an append, add a dated NOTES.md entry carrying the jot's blocks, refresh the ## Open block, and rewrite the router row.

4. Flip the jot row and leave the blocks alone

Set the jot's state to `promoted` · `<slug>`. Cut nothing out of any dated file. The pad records when the thought arrived and how it read at the time, and moving the text destroys that record for no gain.

Done when topics/<slug>/ holds IDEA.md and a first NOTES.md entry naming the jot id, the idea router carries its row, and the jot row reads promoted. Then go to Hand off.

Mode: capture

Write the idea down and stop. It does not discuss, does not research, and offers a session once at most.

1. Match before you create

Read INDEX.md. Match the ask against every slug, every alias, and every summary. When anything is close, show the candidate row and ask whether this belongs on that idea or starts a new one. Read only the router here, so the guard holds.

Two folders for one idea splits the log, and the guard means a later session opens one of them with nothing signalling the other exists.

2. Confirm the slug, then create

On a new idea, propose a slug and confirm it before writing anything, because it is permanent. Then create topics/<slug>/, write IDEA.md from the user's own words, and write the first dated NOTES.md entry.

When the mode fires from another repo, record that repo in the first entry. Where an idea arrived from is usually part of the idea.

3. Write the router row

Add the row with two or three aliases the user would plausibly say later, the one-line summary, and the open question when one is obvious. Status is active.

On an append instead of a create, add the dated NOTES.md entry, refresh the ## Open block, and rewrite the router row.

Done when the router row exists and IDEA.md states the idea in the user's own words. Then go to Hand off.

Mode: session

The mode that thinks.

1. Route to exactly one idea

Read INDEX.md and resolve one slug. On an unknown slug, run capture first, then continue here.

With no idea named, ask. Offer the ideas by last touched, plus "a new idea". Use AskUserQuestion when four or fewer candidates fit, and a numbered list otherwise. Never guess the idea, and never fall through to status.

2. Read only that folder

Read IDEA.md, then NOTES.md, then only the artifacts those two name. Open nothing else.

3. Open with the status report

Print the single-idea report from status as the first thing the user sees. The session then starts from where the last one stopped rather than from a cold restatement.

4. Discuss

The posture: state the strongest version of the idea, then name what would kill it. Build the case first, because an idea argued down before it is stated properly never gets a fair test. Then say the one condition that would end it.

When the user says they are thinking out loud, build only and skip the stress pass. Record the kill condition as the open question either way, so an expansive night still costs the log nothing.

5. Close the session

Compose three writes, then offer them as one save:

1. The dated NOTES.md entry, three to six lines minimum, naming a decision, a rejection, or an open question. That entry is the spine the next session reads.
2. A refreshed ## Open block for IDEA.md, plus a rewritten head when the idea itself changed.
3. The router row, including Last touched.

Print all three under their paths and ask save, edit, or drop, as Saving is a demand, not a default sets out. On a yes, write them in the order above. On a no, write nothing, and say so in the hand-off.

A full session record goes to topics/<slug>/docs/sessions/ only when the user asks for one. Do not offer it.

A parked or closed idea that gets a saved session returns to active under a new dated entry.

Done when the user has seen the composed entry and answered. On a save, the entry names a decision, a rejection, or an open question, the ## Open block matches that entry, and the router row matches both. On a drop, nothing in the folder changed. Then go to Hand off.

Mode: status

Reports, and writes nothing at all.

Cross-idea scope, no idea named

Read INDEX.md and list topics/. Open no topic folder. Print one table sorted by last touched, grouped by status, with each row's age in days (untouched 94 days). Name any folder the router does not list, and say to run session on it to register it.

Read jotpad/INDEX.md and report the pad in one line below the table: the count of live jots, and every jot with three or more entries named as a promotion candidate. Open no dated file. The Entries cell already carries the count, which is what that column is for.

There is no stale marker. A tag most rows would wear inside a year is a verdict on a repo whose whole point is that ideas sit, and the crown below already promotes the cold ones.

Then crown one move:

#	State	Move →
1	an active idea carries a recorded open question	session on the coldest such idea, naming its age
2	a live jot carries three or more entries	promote on that jot
3	an active idea carries no open question	session on it, to find one
4	a building idea carries an open question	session on it
5	every idea is parked or closed, and no live jot exists	say there is no next move, and offer capture

Within rule 1 the crown goes to the coldest idea, not the warmest. Cold plus an open question means the user stopped mid-thought, which is the recoverable case, and it is the row a table sorted by recency buries. Ranking on recency would make the crown restate row one.

No ideas repo, or an empty one? Say so in one line, offer capture or jot, and print no empty table.

Single-idea scope, one idea named

Read IDEA.md, the last two or three NOTES.md entries, and a listing of docs/ without reading the artifacts. Print what the idea is, where it stands, and the open questions. Then crown one move:

#	State	Move →
1	an open question blocks the others	session on that question
2	the idea rests on an unresearched external fact	research
3	the idea is a business and has no verdict	validate
4	the idea is settled enough to shape work	plan it in the project repo
5	nothing is open and no next question exists	close, naming which verdict fits

Done when the printed state matches the files read and exactly one move is crowned. Then go to Hand off.

The dispatch contract

research and validate both send a question to a sibling skill. Four rules govern every dispatch:

• Let the sibling answer inline. researchkit and validatekit both default to answering in the conversation and saving nothing, and that default is ideakit's too. Do not answer their save prompt on the user's behalf.
• Suppress the sibling's hand-off and print ideakit's own. The dispatch is a sub-step, and two competing next-step lines help nobody.
• Offer the artifact after the answer, never before. Ask once whether to keep it. On a yes, write the file yourself from the sibling's inline answer, at topics/<slug>/docs/…, keeping the sibling's own subpath and filename convention. Re-running the sibling to save would land the file in the working directory, because a sibling skill documents its own root and defers to no host. Asking before the dispatch asks before the user knows whether the answer was worth keeping.
• Fold back only what gets saved. On a yes, offer the dated NOTES.md entry naming the question, the answer, and the artifact path, together with the IDEA.md and router updates. On a no, the answer stays in the conversation and the log stays as it was.

The idea's own log holds one authoritative thread of everything the user kept, so a later session reads one file and finds every saved answer.

Mode: research

Route to one slug first, then classify the question before acting.

• A tool, library, framework, or architecture question goes to a research skill (researchkit when installed), answering inline. Offer to keep it at topics/<slug>/docs/research/ afterwards.
• A build-or-drop question is not research. Redirect it to validate.
• A market, competitor, category, or customer-signal question has no sibling owner, so ideakit runs it directly: who else does this, what the category is called, how incumbents price it, and what users publicly complain about. Give every claim a source and a date. Offer the result at topics/<slug>/docs/research/research-<slug>-YYYY-MM-DD.md.

Without a research skill installed, run the comparison against primary sources directly and say plainly that it is the short version.

Done when the user has seen the answer and answered the save offer. On a yes, the artifact exists, the NOTES.md entry names the question and the answer, and IDEA.md and the router row match. On a no, the folder is untouched. Then go to Hand off.

Mode: validate

Route to one slug, then hand the idea to a validation skill (validatekit when installed), answering inline. Offer to keep the write-up at topics/<slug>/docs/validation/ afterwards.

Honor the sibling's side-project off-ramp rather than working around it. It will fire often here, because most ideas in a personal ideas repo are not businesses, and an honest "this is a side project, not a company" is a real answer worth offering to write down.

Offer the verdict, the wedge, and the assignment as one NOTES.md entry, with the router status change when the verdict moves it.

Without a validation skill installed, run a short forcing-question set and a graded verdict, and say plainly that it is the short version.

Done when the user has seen the verdict and answered the save offer. On a yes, the verdict, the wedge, and the assignment are in NOTES.md, and the router status matches the verdict. On a no, the folder is untouched. Then go to Hand off.

Mode: close

Route to one slug. Ask which verdict applies: building, parked, or closed. Require the reason, and refuse to write a verdict without one.

Then write, without a save offer. The verdict and its reason are the demand, and the reason question already gave the user a place to stop.

1. Write a dated verdict entry into NOTES.md, recording what was decided, what evidence decided it, and what would reopen it.
2. Rewrite IDEA.md so the verdict sits at the top of its head.
3. Update the router row.
4. On building, record the implementation repo in the status cell and in the entry.

A closed idea keeps its folder. This mode never deletes a topic folder, never moves a file out of one, and never migrates anything to another repo. An idea that gets built runs its implementation in a separate repo, and the folder stays open for future thinking about the same subject.

Done when the verdict entry, IDEA.md, and the router row agree, and nothing else in the folder changed. Then go to Hand off.

Hand off

Write this section in the procedural register: one instruction per sentence, active voice, present tense, no metaphor.

What changed. Name the entry written, the artifact saved, and the status set. Name what did not change too: a save the user declined, a folder you reported and did not open, a dispatch that ran the short version, a verdict you refused to write without a reason.

Say when a run wrote nothing. State it in one line: this session leaves no record in the repo. Do not soften it, and do not imply the discussion was saved. Offer the save once more only if the user asks.

Where it landed. Give the topic folder path. Give the jot file path and the jot id when a mode wrote a jot. Give the artifact path when a mode wrote one. Give the repo path when this run created the repo.

Next. Crown one move, chosen by state:

• The run wrote a jot → say there is no next step. Do not offer a session on it.
• A live jot carries three or more entries → run promote on that jot.
• The jot just became an idea → run session on the new slug.
• The session stopped on an open question → run session again on that question.
• The open question needs an external fact → run research.
• The idea is a business with no verdict → run validate.
• The idea is settled enough to shape work → plan it in the project repo, with a plan skill (plankit when installed).
• Nothing is open → run close, and name which verdict fits.
• The idea just closed → say there is no next step. Do not invent a follow-up.

Then offer a commit of the ideas repo. Never run it without a yes. Skip the commit offer on a run that wrote nothing.

A status run closes differently. Its whole output is a hand-off, and the dashboard already crowns the move. State that nothing changed. Do not print the move twice, and do not offer a commit.

Notes

• The isolation guard beats every other rule here. Resolve one slug, open one folder. status reports on every idea and opens none of them, which is the guard working rather than an exception to it.
• The user decides what gets kept. Compose the write, show it, and wait. jot, promote, capture, and close are the exemptions, and there are no others.
• capture and jot both stop. Their job is to lose nothing when a thought arrives at a bad moment. Turning either into a session is how the thought gets dropped instead.
• The pad takes anything, and the folder is what gets earned. A jot needs no subject, no slug, and no relevance to an existing idea. promote is the gate, and returning to a thought is what opens it.
• Never rename a slug, and never reuse a jot id. Confirm the slug at creation and leave it alone. The router's Idea column is where a changed name goes.
• This repo ships no code. ideakit never writes application code and never opens issues. An idea that becomes real work moves to a project repo and gets issues there.
• Never commit the ideas repo on its own.
• No writable filesystem (a browser-based agent)? The save offer becomes a print. Say so plainly, print the NOTES.md entry and any artifact as code blocks for the user to save, and give the paths they belong at. Do not report a write that did not happen. status still runs when the filesystem is readable.