Skip to content

README.md

Latest commit

 

History

History
79 lines (60 loc) · 3.34 KB

README.md

File metadata and controls

79 lines (60 loc) · 3.34 KB
Raw

floatie

Floatie helps you turn a vague project idea into a concrete, approved plan — then writes that plan down as a set of standard project files, so scope doesn't drift once you start building with an AI coding agent. Later, it can check back in as the project changes, so that record stays current instead of going stale.

It's an OpenCode plugin. Once installed, you get one new command: /floatie.

What you need first

Floatie only works inside OpenCode — if you don't have that installed yet, follow OpenCode's own install instructions first. Once you can run opencode in a terminal, come back here.

Install

Open a terminal (macOS/Linux: the Terminal app; Windows: PowerShell) and paste this command, then press Enter:

opencode plugin floatie-opencode -g

This installs floatie as a plugin available in every project (-g for global). Leave off -g to install it for just the current project instead.

You should see a small install summary ending in Done, with a line near the bottom saying Added to ...opencode.json — that means it worked.

Try it

  1. Restart OpenCode if it was already running.
  2. Start (or open) any project folder in your terminal and run opencode.
  3. Type /floatie and press Enter.
  4. Answer floatie's questions about what you want to build — even if it's just a rough idea, that's the point.

Floatie will ask a handful of questions one at a time, propose a couple of ways to build your idea, lay out a plan, and ask you to approve it. Nothing is written until you say yes.

Once you approve, floatie writes:

  • AGENTS.md — what the project is and how it's structured, for any coding agent working in it later
  • RULES.md — the hard do's-and-don'ts you stated for the project
  • a skill — the project-specific know-how from your conversation
  • a dated plan doc — the approved plan, as agreed
  • any supporting docs that came up along the way

These are the durable record of what you agreed to build.

Checking back in

Run /floatie again any time after the first setup, and floatie switches to a quick check-in instead of starting over. It reads what's changed in the project since the last plan, asks about anything genuinely worth a question (a new dependency, something that bends a rule in RULES.md, work that looks like new scope), and — with your approval — updates RULES.md, adds a new dated plan doc, or records a decision as an ADR. Nothing gets overwritten silently, and a check-in that finds nothing worth raising is a good outcome.

Troubleshooting

  • /floatie doesn't show up: make sure you restarted OpenCode after installing, and that opencode plugin floatie-opencode -g printed Done without an error.
  • opencode: command not found: install OpenCode first — see opencode.ai/docs — then try again.
  • Install said Done but /floatie still doesn't show up: check that opencode.json (in your project, or your OpenCode config folder if you installed with -g) actually has a floatie-opencode entry — if it's missing, the install didn't take; try running the install command again.
  • You answered something wrong during intake: just say "wait, actually ..." at any point — floatie will take the correction and keep going, no need to restart.