What is a coding-agent plan?

A coding-agent plan is the contract between understanding a software change and implementing it. It records the intended outcome, relevant code, decisions, constraints, ordered work, and verification so another session—or another agent—can continue without reconstructing the entire conversation.

Hostplan gives that contract a stable identity. The plan remains plain Markdown on disk, but it can also have a short URL, lifecycle status, task state, project and branch context, and a direct handoff into a coding agent.

Chat is optimized for conversation, not durable project state. Threads become long, context windows compact, temporary worktrees disappear, and a plan pasted into a message has no independent lifecycle. The next session often has to ask which plan was approved and whether any of it was already completed.

A stored plan separates the artifact from the conversation. The agent can retrieve the current version by id or by project and branch, while a human can read the same plan in a browser.

1. 1

   Write

   Create a focused Markdown implementation plan in the repository or a scratch location.

2. 2

   Store

   Run hsp add. Hostplan detects the project and branch, stores the source, and returns an id and URL.

3. 3

   Approve

   Keep new plans in draft until a human explicitly approves the direction.

4. 4

   Execute

   Move the plan to in-progress, hand it into a coding agent, and check tasks off as work lands.

5. 5

   Finish

   Mark the plan done only after the required verification passes.

hsp add PLAN.md
hsp status <id> approved
hsp status <id> in-progress
hsp check <id> 1 2
hsp status <id> done

Hostplan works locally against files under ~/.hostplan. Hosted plans are private by default and use a share code; publishing is a deliberate command. Live plan pages are excluded from search indexing, including public plans, so a sharing decision does not quietly become a search-distribution decision.