From 3b3e64a35e5f07c2a29f91f4f00d3482c2ee7e44 Mon Sep 17 00:00:00 2001 From: Suleiman Shahbari Date: Sun, 19 Jul 2026 20:43:40 +0300 Subject: [PATCH] feat(framework): ticket format specifies .plan.md (#791) --- .changeset/feat-791-ticket-plan-format.md | 5 +++ .../framework/prompts/ticketing_format.md | 41 +++++++++++++++++++ packages/framework/src/tickets.ts | 2 +- 3 files changed, 47 insertions(+), 1 deletion(-) create mode 100644 .changeset/feat-791-ticket-plan-format.md diff --git a/.changeset/feat-791-ticket-plan-format.md b/.changeset/feat-791-ticket-plan-format.md new file mode 100644 index 00000000..02856e30 --- /dev/null +++ b/.changeset/feat-791-ticket-plan-format.md @@ -0,0 +1,5 @@ +--- +'@gemstack/framework': minor +--- + +Ticket format: specify `tickets/_.plan.md`, the detailed plan that sits beside a ticket and its spike. An agent writing one now has the shape (TLDR, Plan, optional Hard problems and Variability) and, for a low-rated aspect with alternatives, presents them with showChoices() and AWAIT instead of picking silently. diff --git a/packages/framework/prompts/ticketing_format.md b/packages/framework/prompts/ticketing_format.md index 5f878342..7e7de16e 100644 --- a/packages/framework/prompts/ticketing_format.md +++ b/packages/framework/prompts/ticketing_format.md @@ -52,3 +52,44 @@ Typical spike content: - Estimated effort (for each ways to implement it): - Human intervention effort: trivial/low/medium/high/very-high - Token consumption: time estimate (minutes, hours, or days) + +## tickets/_.plan.md + +For an existing ticket (e.g. `tickets/2042-01-01_some-ticket.md`), a detailed plan can be created (`tickets/2042-01-01_some-ticket.plan.md`). + +Body: +```md +# [Plan] Ticket title + +## TLDR + +... + +## Plan + +... + +## Hard problems [optional] + +... + +## Variability [optional] + +... + +[optional: more info (any heading and format you want)] +``` + +Typical plan content: +- Concrete and detailed plan on how to implement the ticket, for example: + - Exhaustive list of all aspects (including edge cases) + - Thorough analysis + - Overview of code changes + - ... +- Hard problems + - Exhaustive list of all aspects with low confidence regarding how to solve them (the hard problems), with explanation why +- Variability + - List all aspects that need to be implemented + - Give a rating to each aspect (from 0 to 10) following this criteria: is there an obviously optimal way to implement it (10), or is it highly unclear whether it can be implemented in a better way (0)? + - Explore and suggest alternatives for aspects with a low rating + - For each aspect that has alternatives: list all alternatives sorted in a sensible order, then ask the user to pick one with showChoices() and AWAIT (one question per aspect, recommending the alternative you'd pick) diff --git a/packages/framework/src/tickets.ts b/packages/framework/src/tickets.ts index 734aafff..ac330692 100644 --- a/packages/framework/src/tickets.ts +++ b/packages/framework/src/tickets.ts @@ -12,7 +12,7 @@ export const TICKETS_DIR = 'tickets' /** * The ticket-format spec (#684): the static reference an agent opens to learn the - * `tickets/_.md` (and `.spike.md`) file shape. Per Rom's #674 call it ships + * `tickets/_.md` (and `.spike.md` / `.plan.md`) file shape. Per the #674 call it ships * *inside the installed package* rather than being materialized into the repo, so a future * breaking change to the format rides with the package version instead of going stale in a * committed file. The package ships `prompts/ticketing_format.md` (see the `files` allowlist),