[sabind]

Why

Closes #47
Closes #48

On every spec written with start-task, each of the three documents was printed in full into the conversation before its approval question, and again after every change-request round. A mid-sized design runs to a couple of hundred lines, so a three-document spec with one revision each put six full documents into the conversation. The author reads the file in an editor anyway, so the print added bulk without adding trust. In the author's words: it is important to make sure we are able to explain what the summary is for explicitly, so we can confirm the right summaries are being produced at the right time.

Specs also move out of .claude/: the eval sandbox refuses every write under that folder, so no case could grade a spec being written or ticked, and the plugin will be forked for tools with .cursor/ and .codex/ folders, so the spec folder should name the plugin rather than one tool.

What

On the spec route, start-task now shows each document as its path plus a summary in a fixed shape per document, and after "Changes needed" shows the path plus what changed per section. Specs live in .freethinking/specs/<task>/ instead of .claude/specs/<task>/, in the plugin text, the evals and this repository's own records. The plugin is 0.14.0.

Changes

• start-task shows a path and a summary instead of the full text. plugins/freethinking/skills/start-task/SKILL.md gains a "Showing a document" section, the Hand-backs bullet changes to match, and steps 1, 4, 5 and 6 each set their summary's shape: requirements as one entry per requirement with its user story quoted, then open questions; design as each key decision quoted, then the rest summarised; tasks as a table of leaf tasks by wave; a revision as one line per changed section. Author: "we're basically highlighting important parts of the docs and then summarizing the rest", and the summary's purpose is stated explicitly so the right summary at the right time can be confirmed. Step 3 also names the route by its token, Bug_Route, Executor_Route or Spec_Route: the start-task eval names-task-and-asks greps for the token and one run of three had left it implicit.
• The plugin README's start-task row says the skill shows each document as its path and a short summary. Requirement 6.3 of the spec: the README describes what the skill does.
• New eval case evals/skills/start-task/summarises-requirements/, eight graders: the requirements file is written under .freethinking/specs/, the reply names its path, no heading of the document is reprinted, no SHALL criterion is reproduced, a user story is quoted, every entry quotes a story, the Approve question is offered, and no code is written. Requirement 7: the behaviour is proved by an eval, not a check that greps the skill.
• Spec folder moves to .freethinking/specs/ in the plugin text: both skills, the task-executor agent, the workflow rule's record bullet, the root README and the plugin README, which gains a sentence under "Tune the plugin for a repository" and an upgrade note under "Stay up to date". Version 0.14.0. Author: "we can store the specs not in .claude/ that works well since we will fork and have .cursor/ .codex/ ... later", and .freethinking/ because at a bare specs/ "it's unclear who the author is".
• Spec folder moves in the evals: four files/.claude/specs fixtures renamed with git mv, every prompt, grader, scaffold and case README repathed, and the sandbox note in evals/README.md rewritten to say that writes under .claude/ are refused even when granted and that specs under .freethinking/specs/ can be graded. Requirement 8.3.
• Tick graders on the two implement-spec cases that build the calc spec, now that the sandbox lets a skill write under .freethinking/: works-one-wave checks tasks.md has - [x] 1. and still - [ ] 2., works-all-waves checks both are ticked. Each case's README lists them and says the one thing left unchecked is whether a tick came after its wave review. Author: "lets keep the stuff accurate".
• This repository's spec records move with git mv .claude/specs .freethinking/specs, 42 renames at 100% similarity, content untouched, and this task's own spec is added at .freethinking/specs/spec-approval-summary/. Author: "Move them, content untouched".

Testing

make validate passes: 23 checks and the three strict validators.

Eval targets, three runs per case, on the final text:

start-task ($2.72)

Case	Score	Pass
bug-offers-bugfix	1.00	3/3
contained-change-offers-executor	1.00	3/3
names-task-and-asks	1.00	3/3
summarises-requirements	1.00	3/3
wrong-repo-asks-fit	0.94	2/3, then 1.00 on a three-run rerun

The wrong-repo-asks-fit miss was names-the-task, which greps for link-shortener; the rerun passed all three.

implement-spec ($7.53)

Case	Score	Pass
invalid-graph-stops	0.83	2/3, then 1.00 on a three-run rerun
no-spec-recommends-start-task	1.00	3/3
offers-choice-on-discovery	1.00	3/3
works-all-waves	1.00	3/3
works-one-wave	1.00	3/3

The invalid-graph-stops miss was a run that returned after three turns; the rerun passed all three.

With the tick graders added, works-one-wave and works-all-waves were run again at three runs: 1.00 each, every tick grader matched in every run ($4.66).

workflow rule ($2.37)

Case	Score	Pass
bug-routes-to-bugfix	0.80	0/3
closed-spec-is-a-record	1.00	3/3
feature-routes-to-start-task	1.00	3/3
pr-routes-to-pr-skill	1.00	3/3
small-change-skips-spec	1.00	3/3
spec-routes-to-implement-spec	1.00	3/3

bug-routes-to-bugfix fails the same grader, states-symptom, three of three on origin/main as well, so it is pre-existing and not changed by this branch.

Risk and rollout

A repository with specs under .claude/specs/ must run git mv .claude/specs .freethinking/specs once after upgrading: start-task and implement-spec look only in the new folder. The README's upgrade note says so. A session still on 0.13.0 looks in the old folder until the plugin is updated.

Notes for reviewers

Look at plugins/freethinking/skills/start-task/SKILL.md first: the "Showing a document" section and the closing paragraphs of steps 4, 5 and 6 are the behaviour change. Follow-up: the bug-routes-to-bugfix eval fails on main on a grader that wants the word "symptom" in the trace.

🤖 Generated with Claude Code