diff --git a/.claude/specs/bugfix-cx-and-handoff/design.md b/.freethinking/specs/bugfix-cx-and-handoff/design.md
similarity index 100%
rename from .claude/specs/bugfix-cx-and-handoff/design.md
rename to .freethinking/specs/bugfix-cx-and-handoff/design.md
diff --git a/.claude/specs/bugfix-cx-and-handoff/requirements.md b/.freethinking/specs/bugfix-cx-and-handoff/requirements.md
similarity index 100%
rename from .claude/specs/bugfix-cx-and-handoff/requirements.md
rename to .freethinking/specs/bugfix-cx-and-handoff/requirements.md
diff --git a/.claude/specs/bugfix-cx-and-handoff/tasks.md b/.freethinking/specs/bugfix-cx-and-handoff/tasks.md
similarity index 100%
rename from .claude/specs/bugfix-cx-and-handoff/tasks.md
rename to .freethinking/specs/bugfix-cx-and-handoff/tasks.md
diff --git a/.claude/specs/contributing-guide/design.md b/.freethinking/specs/contributing-guide/design.md
similarity index 100%
rename from .claude/specs/contributing-guide/design.md
rename to .freethinking/specs/contributing-guide/design.md
diff --git a/.claude/specs/contributing-guide/requirements.md b/.freethinking/specs/contributing-guide/requirements.md
similarity index 100%
rename from .claude/specs/contributing-guide/requirements.md
rename to .freethinking/specs/contributing-guide/requirements.md
diff --git a/.claude/specs/contributing-guide/tasks.md b/.freethinking/specs/contributing-guide/tasks.md
similarity index 100%
rename from .claude/specs/contributing-guide/tasks.md
rename to .freethinking/specs/contributing-guide/tasks.md
diff --git a/.claude/specs/directory-listing/design.md b/.freethinking/specs/directory-listing/design.md
similarity index 100%
rename from .claude/specs/directory-listing/design.md
rename to .freethinking/specs/directory-listing/design.md
diff --git a/.claude/specs/directory-listing/requirements.md b/.freethinking/specs/directory-listing/requirements.md
similarity index 100%
rename from .claude/specs/directory-listing/requirements.md
rename to .freethinking/specs/directory-listing/requirements.md
diff --git a/.claude/specs/directory-listing/tasks.md b/.freethinking/specs/directory-listing/tasks.md
similarity index 100%
rename from .claude/specs/directory-listing/tasks.md
rename to .freethinking/specs/directory-listing/tasks.md
diff --git a/.claude/specs/eval-hygiene/design.md b/.freethinking/specs/eval-hygiene/design.md
similarity index 100%
rename from .claude/specs/eval-hygiene/design.md
rename to .freethinking/specs/eval-hygiene/design.md
diff --git a/.claude/specs/eval-hygiene/requirements.md b/.freethinking/specs/eval-hygiene/requirements.md
similarity index 100%
rename from .claude/specs/eval-hygiene/requirements.md
rename to .freethinking/specs/eval-hygiene/requirements.md
diff --git a/.claude/specs/eval-hygiene/tasks.md b/.freethinking/specs/eval-hygiene/tasks.md
similarity index 100%
rename from .claude/specs/eval-hygiene/tasks.md
rename to .freethinking/specs/eval-hygiene/tasks.md
diff --git a/.claude/specs/implement-spec/design.md b/.freethinking/specs/implement-spec/design.md
similarity index 100%
rename from .claude/specs/implement-spec/design.md
rename to .freethinking/specs/implement-spec/design.md
diff --git a/.claude/specs/implement-spec/requirements.md b/.freethinking/specs/implement-spec/requirements.md
similarity index 100%
rename from .claude/specs/implement-spec/requirements.md
rename to .freethinking/specs/implement-spec/requirements.md
diff --git a/.claude/specs/implement-spec/tasks.md b/.freethinking/specs/implement-spec/tasks.md
similarity index 100%
rename from .claude/specs/implement-spec/tasks.md
rename to .freethinking/specs/implement-spec/tasks.md
diff --git a/.claude/specs/pr-skill-ticket/design.md b/.freethinking/specs/pr-skill-ticket/design.md
similarity index 100%
rename from .claude/specs/pr-skill-ticket/design.md
rename to .freethinking/specs/pr-skill-ticket/design.md
diff --git a/.claude/specs/pr-skill-ticket/requirements.md b/.freethinking/specs/pr-skill-ticket/requirements.md
similarity index 100%
rename from .claude/specs/pr-skill-ticket/requirements.md
rename to .freethinking/specs/pr-skill-ticket/requirements.md
diff --git a/.claude/specs/pr-skill-ticket/tasks.md b/.freethinking/specs/pr-skill-ticket/tasks.md
similarity index 100%
rename from .claude/specs/pr-skill-ticket/tasks.md
rename to .freethinking/specs/pr-skill-ticket/tasks.md
diff --git a/.claude/specs/report-skill/design.md b/.freethinking/specs/report-skill/design.md
similarity index 100%
rename from .claude/specs/report-skill/design.md
rename to .freethinking/specs/report-skill/design.md
diff --git a/.claude/specs/report-skill/requirements.md b/.freethinking/specs/report-skill/requirements.md
similarity index 100%
rename from .claude/specs/report-skill/requirements.md
rename to .freethinking/specs/report-skill/requirements.md
diff --git a/.claude/specs/report-skill/tasks.md b/.freethinking/specs/report-skill/tasks.md
similarity index 100%
rename from .claude/specs/report-skill/tasks.md
rename to .freethinking/specs/report-skill/tasks.md
diff --git a/.freethinking/specs/spec-approval-summary/design.md b/.freethinking/specs/spec-approval-summary/design.md
new file mode 100644
index 0000000..01f676e
--- /dev/null
+++ b/.freethinking/specs/spec-approval-summary/design.md
@@ -0,0 +1,170 @@
+# Design Document
+
+## Overview
+
+The start-task skill gains one short section, "Showing a document", that holds the shape every spec document is shown in for approval: its path first, one sentence that the author can open the file, then the document's content in a fixed shape per document, quoting only what that shape names and summarising the rest, in the same message as the approval question and never the whole document; and the shape of a revision, the path plus what changed, section by section, in the same message as the question. The three writing steps, the resume sentence in step 1 and the Hand-backs bullet refer to that section instead of saying "show the author the document", and each writing step sets its shape: each requirement's user story quoted for the requirements, each key decision quoted then the rest summarised for the design, a table of leaf tasks by wave for the task list. The README's start-task row says the same in a clause. One new eval case answers the spec questions inside the request so the run reaches a written `requirements.md`, and grades the hand-back on naming the path, quoting a user story, giving one entry per requirement and containing no criterion. Beyond those, the spec folder moves from `.claude/specs/` to `.freethinking/specs/` in the plugin text, the evals and this repository's records, because the eval sandbox refuses every write under `.claude/` and the folder should name the plugin, not one tool.
+
+## Architecture
+
+```mermaid
+flowchart LR
+ W["Step 4, 5 or 6 writes
the Spec_Document"] --> S["Showing a document:
path, open-the-file sentence,
the step's shape: quote what it names,
summarise the rest"]
+ S --> Q["Approval_Question
same message"]
+ Q -- "Changes needed" --> R["Revise the file"]
+ R --> V["Revision_Summary:
path, what changed per section,
what was not applied and why"]
+ V --> Q
+ Q -- "Approved" --> N["Next step"]
+```
+
+**Key decision: one section holds the common shape, each step holds its depth.** The path line, the open-the-file sentence, the same-message rule, the rule to quote only what the shape names and the revision shape are the same for all three documents, so they are written once in a section the steps name (Requirement 6.2, 1.1 to 1.3, 5.1 to 5.4). What a summary holds differs by document and is the thing the author tuned, so it stays in the step that writes the document, where the author of the skill reads it beside the document's sections (Requirements 2, 3, 4). The trade-off is one more cross-reference inside the skill; the alternative, repeating the common shape three times, is the kind of duplication the no-cross-skill-internals practice exists to avoid, and a change to the shape would have to be made in three places.
+
+**Key decision: the summary and the question go in one message, summary first.** A report written before a tool call is the thing most likely to be dropped, as the fit-question fix in the workflow-rule-wording spec showed; the step says "in the same message" so the summary is what the author reads above the options (Requirement 1.1). Rejected: putting the summary inside the question text. AskUserQuestion's question is one line and its option descriptions are short, so a summary there would be truncated or squeezed into the descriptions.
+
+**Key decision: three fixed shapes, one per document, each quoting only what its shape names.** The requirements summary quotes each requirement's user story, its first sentence, which says what it is for and for whom, and leaves the criteria to the file; the design summary quotes each key decision paragraph, the things the author reviews, then summarises the rest for discussion; the tasks summary is the table of leaf tasks by wave that implement-spec already shows at its graph check (Requirements 1.4, 2, 3, 4, 5.4). A fixed shape per document makes the summary predictable and short with no size bound to police. Rejected: quoting nothing, the first draft, which left the author approving a paraphrase of the lines that matter; a free choice of highlights under a size bound, the second draft, which the wave review found unsettled on a small design and ambiguous about what a line is; and quoting every criterion, which is the full print this change removes.
+
+**Key decision: the eval case reaches the document by answering the spec questions in the request.** The collaboration rule says an answer given in the request counts at its question, so a prompt that carries the four answers lets the skill write `requirements.md` and stop at the approval question in one run (Requirement 7.1). Rejected: a multi-turn case, which the eval harness does not run, and a case that grades the design or tasks hand-back, which would need two approvals the harness cannot give. The requirements hand-back is the one reachable in a single run, and the three steps share the common shape, so proving it there proves the frame; the design and tasks depths are read by the wave reviewer against Requirements 3 and 4.
+
+**Key decision: deterministic graders for "not reprinted", "quotes a user story" and "no criterion reproduced", a literal llm grader for "every entry quotes a story".** `match: not_contains` on the document's own section headings, anchored to the start of a line so the words in prose are allowed, catches a reprinted document; a regex on `As an? .+, I want` proves a user story was quoted; and `match: not_contains` on `\bSHALL\b` proves no criterion was reproduced, since every criterion carries the word and no summary does. What is left for a judge is whether every list item quotes a story and no section is printed, two literal checks with an allowed-list, after two earlier wordings failed correct replies three votes to none (Requirement 7.2). A judge that sees only the reply cannot count the document's requirements, so the grader is named `every-entry-quotes-a-story` for what it proves, and the one-entry-per-requirement count is read by the wave reviewer and the first real spec. The case confirms at three runs.
+
+**Key decision: specs move to `.freethinking/specs/`, out of `.claude/`.** Two probe runs showed the sandbox refusing the Write of `requirements.md` under `.claude/specs/`, with Write granted and with a path-scoped `Write(.claude/**)` grant, and a third showed a committed `CLAUDE.md` is not loaded, so no per-repository instruction can redirect the skill there. The folder moves to the plugin's own `.freethinking/`, which already holds repository overrides: it names the plugin rather than one tool, so a fork for Cursor or Codex keeps the same path, and the sandbox lets a skill write there (Requirement 8). Rejected: `specs/` at the root, which does not say who writes it; a `.freethinking/` setting file naming the folder, which would widen three components to serve one eval; and grading the resume path from a committed unapproved document, which leaves the write unproven.
+
+## Components and Interfaces
+
+### plugins/freethinking/skills/start-task/SKILL.md
+
+Five edits, each quoted as it will read.
+
+1. The Hand-backs bullet in "Working with the author" (Requirement 6.1). Today: "On Spec_Route, each document in full." After: "On Spec_Route, each document as its path and a summary, and each revision as its path and what changed, as the Showing a document section says."
+
+2. A new section after "Working with the author" and before "## 1. Name the task and find its spec" (Requirements 1.1 to 1.3, 5.1 to 5.4, 6.2):
+
+```markdown
+## Showing a document
+
+A document is shown for approval as its path and a summary, never as its whole text: the author opens the file to read it. The summary and the approval question go in one message, the summary first. The summary opens with the document's path from the repository root on its own line, says once that the author can open the file before answering, then gives the document's content in the shape the step that wrote it sets, quoting from the document only what that shape names and summarising the rest in plain words.
+
+After `Changes needed`, revise the file, then show it again as its path and one line per section that changed, saying what changed in it and quoting a user story or key decision that changed; a section that did not change is not listed. If part of the request was not applied, say which part and why. The revision and the step's approval question go in one message, the revision first.
+```
+
+3. Step 1, the resume sentence (Requirement 1.6). Today: "Read what is there and resume at the first document that is missing or that the author says is not approved." After: "Read what is there and resume at the first document that is missing or that the author says is not approved; if that document exists, it is shown as the Showing a document section says, then its step's approval question is put."
+
+4. The closing paragraph of each writing step (Requirements 2, 3, 4). Step 4, today: "Then show the author the document and ask with the AskUserQuestion tool, header `Approve`, ..." After:
+
+ "Then show the document as the Showing a document section says. Its summary is one entry per requirement, in order: the requirement's number and title, then its user story, the requirement's first sentence, quoted; no criterion is quoted and the glossary is not listed. After the entries, name any question the requirements leave open that the author did not answer. Ask with the AskUserQuestion tool, header `Approve`, options `Approved` and `Changes needed`, whether these requirements say what they want built, with anything missing or wrong in the free text. Iterate until approved."
+
+ Step 5, today: "Name anything that does not trace. Then show the author the document and ask ..." After:
+
+ "Then show the document as the Showing a document section says. Its summary opens with each key decision quoted, its paragraph, in the document's order, as the things to review, then summarises the rest for discussion: the main flows and design concepts, the parts, what each is for and how the work moves through them, in a few lines, then anything that does not trace. It leaves out the data fields and types, the operations table, the correctness properties, the error-handling rows and the testing strategy. Ask with the AskUserQuestion tool, header `Approve`, options `Approved` and `Changes needed`, whether this design is how they want the requirements met, with anything missing or wrong in the free text. Iterate until approved."
+
+ Step 6, today: "Then show the author the document and ask ..." After:
+
+ "Then show the document as the Showing a document section says. Its summary is a table with one row per leaf task in wave order, with columns for the wave, the task's number, what it builds in a line, whether it is an optional test, the requirements it cites and the design property it names if any; none of a task's detail bullets. Ask with the AskUserQuestion tool, header `Approve`, options `Approved` and `Changes needed`, whether these tasks build the design in an order they accept, with anything missing or wrong in the free text. Iterate until approved."
+
+5. Nothing else in the skill changes: the description, the ground rules, the Stops and How-it-asks bullets, the routes and step 7 stay as they are (Requirements 1.5, 6.4).
+
+| Operation | Input | Output | Requirements |
+|-----------|-------|--------|--------------|
+| Show a document | a written Spec_Document and its step's shape | path, open-the-file sentence, the step's shape, then the Approval_Question, in one message | 1.1 to 1.6, 2, 3, 4 |
+| Show a revision | the revised Spec_Document and the change request | path, one line per changed section with a changed user story or key decision quoted, unapplied parts with reasons, then the Approval_Question, in one message | 5.1 to 5.4 |
+
+### plugins/freethinking/README.md
+
+The start-task row's last sentence (Requirement 6.3), today: "..., following the team template, with you approving each document before the next." After: "..., following the team template, showing you each document as its path and a short summary and asking you to approve it before the next."
+
+### evals/skills/start-task/summarises-requirements/
+
+A new case on the calc fixture (Requirement 7).
+
+- `case.yaml`: `schema_version: "1.1"`, `name: summarises-requirements`, `context.scaffold_script: scaffold.sh`.
+- `scaffold.sh`: a regular executable file, the same as `names-task-and-asks/scaffold.sh`: finds the repository root and runs `evals/fixtures/setup.sh calc main`.
+- `prompt.md` frontmatter: `description`, that with the spec questions answered in the request start-task writes `requirements.md` for the calc fixture and hands it back as its path and one entry per requirement with its user story quoted, not the text, then asks for approval; `tags: [skill, start-task]`; `max_turns: 12`, since the run reads the fixture, the template and writes a file; `allowed_tools: [Read, Glob, Grep, Write, Edit, Agent, Skill]`; `expected_outcome` in the same words as the description, with the path named, one entry per requirement with its user story quoted, anything the skill decided listed as an open question, no criterion quoted, no section of the document reprinted, `Approved` and `Changes needed` offered, and no code written. Prompt:
+
+ "/freethinking:start-task Keep a history of every calculation: record each operation with its operands and result as it runs, and add a way to list the history. Answers to the spec questions: it is for a developer using the calc package from a script, so they can see afterwards what was computed and in what order; out of scope is keeping the history beyond the process or sharing it between processes, and clearing the history; no constraints beyond the standard library and the existing tests passing; keep it in a new module that wraps the operations, so only calls made through it are recorded, and record a call that raises as an entry holding the error instead of a result. I will not answer further questions in this run: decide anything else yourself and list it as an open question in the hand-back."
+
+ The last sentence stops the skill from waiting on a further question, which the first probe showed it asks when the answers leave a gap, and exercises Requirement 2.3, the open questions after the entries. The description and expected_outcome say that anything the skill decided is listed as an open question.
+
+- Graders, seven:
+
+| Grader | Type | Checks |
+|--------|------|--------|
+| `writes-requirements` | `file_exists`, path `.freethinking/specs/*/requirements.md`, `exists: true` | the document was written during the run, in the Spec_Folder |
+| `names-the-path` | `regex`, pattern `\.freethinking/specs/[a-z0-9-]+/requirements\.md` | the final message names the file |
+| `not-reprinted` | `regex`, pattern `^#+\s*Acceptance Criteria\|^## Glossary`, flags `m`, `match: not_contains` | no heading of the document is in the final message; the words in prose are allowed |
+| `offers-approval` | `regex`, pattern `^\s*(?:[-*•]\|\d+[.)])\s*[*_\x60]*Approved\b`, flags `im` | the approval question is put, its option on its own line as the sibling cases grade |
+| `quotes-a-user-story` | `regex`, pattern `As an? .+, I want` | at least one requirement's user story is quoted in the final message |
+| `no-criteria-reproduced` | `regex`, pattern `\bSHALL\b`, `match: not_contains` | no acceptance criterion is reproduced: every criterion carries SHALL and no summary does |
+| `every-entry-quotes-a-story` | `llm`, judging the reply alone | checks only two things: before the approval options, a list in which every item quotes a user story that begins "As a" and contains "I want" and "so that"; and no section of the document printed. PASS when both hold, FAIL when either does not. It says what is allowed and never a reason to fail: a summary sentence after a quote, a bracketed reference such as (2.2), a list of decisions or open questions after the items, bold or backticks, options in plain text. It does not prove one entry per requirement, which the judge cannot count from the reply |
+
+The `no-code-written` grader of the siblings is not carried: this case writes a file on purpose, and `file_exists` counts only files created during the run, so a grader on `**/*.py` with `exists: false` is added instead as `no-code-written` to keep the "writes no code" promise: no Python file is created anywhere in the workspace, since the skill writes only Markdown under `.freethinking/specs/`. That makes eight graders. The Makefile's start-task target already grants Write and Edit and runs scaffolds, so no Makefile change.
+
+### The spec folder move
+
+One replacement, `.claude/specs` to `.freethinking/specs`, in three groups of files, each its own task (Requirement 8).
+
+| Group | Files | Beyond the replacement |
+|-------|-------|------------------------|
+| Plugin text and READMEs | `skills/start-task/SKILL.md`, `skills/implement-spec/SKILL.md`, `agents/task-executor.md`, `rules/workflow.md`, the plugin README, the root README | the plugin README's "Tune the plugin for a repository" section gains, after its first sentence: "The same folder holds the specs: `start-task` writes each task's three documents to `.freethinking/specs//`, and `implement-spec` reads them there." |
+| Evals | the four `files/.claude/specs` fixture folders under `evals/skills/implement-spec/` (three) and `evals/rules/workflow/closed-spec-is-a-record/` (one), moved with `git mv`; every prompt, grader, scaffold and case README under `evals/` that names the path, the new case's `prompt.md` and graders included; `evals/README.md` | the sandbox note becomes: "Writes and edits under `.claude/` in the workspace are refused even when Write or Edit is granted, and so is a shell fallback; a path-scoped grant such as `Write(.claude/**)` does not lift it, and a committed `CLAUDE.md` is not loaded. Specs live under `.freethinking/specs/`, which the sandbox lets a skill write, so a spec being written or ticked can be graded there." |
+| Records | `git mv .claude/specs .freethinking/specs`, the eleven folders, this spec's included | content untouched; `.claude/settings.json` stays |
+
+The hook output and the rules size are unaffected beyond the one path in the workflow rule's record bullet, which `make check` proves.
+
+## Data Models
+
+The Document_Summary, as text:
+
+```text
+.freethinking/specs//.md
+
+
+" then "> " per requirement, then any open question>
+ " per key decision, in order, then a few lines of flows and concepts, then anything that does not trace>
+
+```
+
+The Revision_Summary, as text:
+
+```text
+.freethinking/specs//.md
+- : , with "> " when a user story or key decision changed
+- Not applied: , because
+```
+
+The eval case folder follows `checks/test_eval_cases.py`: `prompt.md` with its frontmatter fields, `graders/*.md` each with `type` and that type's fields, `case.yaml` naming an executable regular-file `scaffold.sh`.
+
+## Correctness Properties
+
+### Property 1: A document is never printed for approval
+
+*For any* spec document start-task shows for approval, first time or after a revision, the message holds the document's path, quotes from the file only user stories and key decision paragraphs, and contains no acceptance criterion, section heading, data table, property, error row, testing strategy or task detail bullet from the file.
+
+**Validates: Requirements 1.1, 1.2, 1.4, 2.2, 3.3, 4.2, 5.4**
+
+### Property 2: The summary and the question travel together
+
+*For any* approval start-task asks on Spec_Route, the summary or revision summary is in the same message as the question, above it.
+
+**Validates: Requirements 1.1, 5.1**
+
+### Property 3: Every requirement, wave and task has its line
+
+*For any* requirements summary, the number of entries equals the number of requirements in the file; for any tasks summary, every leaf task of the dependency graph has exactly one row, and the rows run in wave order.
+
+**Validates: Requirements 2.1, 4.1**
+
+## Error Handling
+
+| Condition | Category | Behavior | Requirements |
+|-----------|----------|----------|--------------|
+| The author answers Changes needed with a request that contradicts an approved earlier document | CONFLICT | say so in the revision summary as a part not applied, with the reason, and ask again | 5.3 |
+| A change request names a section the document does not have | VALIDATION | say so as a part not applied; revise the rest | 5.3 |
+| The sandbox refuses the write of `requirements.md` | SANDBOX | seen twice under `.claude/specs/`, with Write granted and with `Write(.claude/**)`: "Permission to use Write has been denied because Claude Code is running in don't ask mode"; the Spec_Folder moves out of `.claude/`; if `.freethinking/` is refused too, stop and report | 7.1, 8.5 |
+| The eval run ends before the file is written for another reason | TURNS | `writes-requirements` fails; read the trace, raise `max_turns` as the evals README says, not the grader | 7.1 |
+| The eval's llm grader fails while the regex graders pass | GRADER | read the reply in the report; a judge failing a reply that meets the grader's two literal checks is a grader fault, so make the grader more literal; a reply that fails them is the skill's fault, so fix the skill text | 7.2, 7.4 |
+| An existing start-task case drops below its last result | REGRESSION | the edits touch only the closing paragraphs and the new section, so a drop points at the section's wording; shorten it and rerun | 7.4 |
+
+## Testing Strategy
+
+- `make validate` after the skill and README edits and after the case is added: the skills validator on the frontmatter, `checks/test_eval_cases.py` on the case, `checks/test_descriptions.py` on the README's agreement with the skills.
+- `make eval-skill-start-task EVAL_ARGS="--runs 1 --case summarises-requirements"` to iterate the new case, then the whole target at the default three runs, since the case has an llm grader, with the table pasted into the pull request's Testing section (Requirement 7.4). The four existing cases are the regression check for the edited steps.
+- There is no automated test for the entry count of the requirements summary, the requirements half of Property 3, since a grader that sees only the reply cannot count the document's requirements; nor for the design and tasks summaries, which no single-run case reaches; the wave reviewer reads the step 5 and step 6 text against Requirements 3 and 4, and the first real spec written with the changed skill is the check.
diff --git a/.freethinking/specs/spec-approval-summary/requirements.md b/.freethinking/specs/spec-approval-summary/requirements.md
new file mode 100644
index 0000000..f6d79ef
--- /dev/null
+++ b/.freethinking/specs/spec-approval-summary/requirements.md
@@ -0,0 +1,113 @@
+# Requirements Document
+
+## Introduction
+
+On its spec route, the start-task skill writes `requirements.md`, `design.md` and `tasks.md` in turn and asks the author to approve each one. Today it prints each document in full into the conversation before the approval question, and prints it again after every change-request round, so a three-document spec with one revision each puts six full documents in front of the author, who reads the file in an editor anyway. This change makes the skill show the document's path and a short summary instead: enough for the author to know what they are approving at a high level and to trust it, without flooding the conversation. The author opens the file before approving; the approval question itself does not change. Only start-task changes. GitHub issue #47 is the ticket.
+
+## Glossary
+
+- **Skill**: The start-task skill at `plugins/freethinking/skills/start-task/SKILL.md`.
+- **Author**: The person running the Skill, who approves each document.
+- **Spec_Folder**: `.freethinking/specs//`, where the three Spec_Documents of a task live.
+- **Spec_Document**: One of `requirements.md`, `design.md` and `tasks.md` in the Spec_Folder.
+- **Approval_Question**: The question the Skill puts with the AskUserQuestion tool after each Spec_Document, header `Approve`, options `Approved` and `Changes needed`.
+- **Document_Summary**: The text the Skill shows in place of a Spec_Document's body: the document's path, its Highlights, and a short account of the rest at the depth the requirements below set for that document.
+- **Highlight**: A passage of a Spec_Document that its Document_Summary quotes verbatim because the document's shape names it: the user story of each requirement in `requirements.md`, and the paragraph of each Key_Decision in `design.md`.
+- **Leaf_Task**: A checkbox task in `tasks.md` with no sub-tasks, the unit the Task Dependency Graph lists.
+- **Revision_Summary**: The text the Skill shows after revising a Spec_Document on a change request: the document's path and what changed, section by section.
+- **Key_Decision**: A design decision that chose between alternatives with a real trade-off, so the Author may disagree with it.
+- **Wave**: One entry of the `waves` block in a `tasks.md` Task Dependency Graph.
+- **Hand_Backs_Bullet**: The bullet in the Skill's "Working with the author" section that says what the Skill hands back on each route.
+- **README**: The plugin README at `plugins/freethinking/README.md`, whose Skills table describes the Skill.
+- **Eval_Case**: A folder under `evals/` with a `prompt.md` and graders, run by its component's make target; Requirement 7's case is under `evals/skills/start-task/`, run with `make eval-skill-start-task`.
+- **System**: The handbook plugin: the Skill, the README and the Eval_Cases.
+
+## Requirements
+
+### Requirement 1: The path and a summary replace the full text
+
+**User Story:** As an Author approving a Spec_Document, I want the Skill to tell me where the file is and what it says at a high level, so that I can open the file and approve it without the whole document being printed into the conversation.
+
+#### Acceptance Criteria
+
+1. WHEN the Skill has written a Spec_Document, THE Skill SHALL show a Document_Summary and put the Approval_Question, in that order and in the same message, and SHALL not reproduce the Spec_Document's body in the conversation.
+2. THE Document_Summary SHALL open with the Spec_Document's path, relative to the repository root, on its own line.
+3. THE Document_Summary SHALL say, once, that the Author can open the file before answering.
+4. THE Document_Summary SHALL quote from the Spec_Document only the Highlights Requirements 2 and 3 name for that document, and SHALL summarise the rest, so the Document_Summary stays far shorter than the file.
+5. THE Approval_Question SHALL keep its header, its options and its wording as they are today.
+6. WHEN the Skill resumes at an existing Spec_Document that the Author says is not approved, THE Skill SHALL show it the same way, as a Document_Summary followed by the Approval_Question.
+
+### Requirement 2: The requirements summary
+
+**User Story:** As an Author, I want the requirements summarised as each requirement's user story, so that I know at a high level what is being built and for whom before I read the criteria in the file.
+
+#### Acceptance Criteria
+
+1. THE Document_Summary for `requirements.md` SHALL list every requirement, in order, as one entry giving its number and title, then its user story, the first sentence of the requirement, quoted verbatim as its Highlight.
+2. THE Document_Summary for `requirements.md` SHALL quote no acceptance criterion and SHALL not list the glossary.
+3. IF the requirements leave a question open that the Author did not answer, THEN THE Document_Summary SHALL name it after the requirement entries.
+
+### Requirement 3: The design summary
+
+**User Story:** As an Author, I want the design's key decisions quoted for review and the rest summarised for discussion, so that I can push back on a decision and talk through the shape of the solution without reading the lower-level detail in the conversation.
+
+#### Acceptance Criteria
+
+1. THE Document_Summary for `design.md` SHALL open with each Key_Decision as a Highlight, its decision paragraph quoted verbatim, in the document's order, as the things for the Author to review.
+2. THE Document_Summary for `design.md` SHALL then summarise the rest for discussion: the main flows and design concepts, the components or parts, what each is for, and how a request or piece of work moves through them, in a few lines.
+3. THE Document_Summary for `design.md` SHALL leave out the lower-level content: data fields and types, the operations table, the correctness properties, the error-handling rows and the testing strategy.
+4. WHEN the Skill's traceability check finds a requirement the design does not satisfy or a decision that traces to no requirement, THE Document_Summary SHALL name it, as the Skill already requires.
+
+### Requirement 4: The tasks summary
+
+**User Story:** As an Author, I want the task list shown as a table of its leaf tasks by wave, so that I can accept the order of the work at a glance, in the shape implement-spec later shows me at its graph check.
+
+#### Acceptance Criteria
+
+1. THE Document_Summary for `tasks.md` SHALL be a table with one row per Leaf_Task in Wave order, with columns for the Wave, the task's number, what it builds in one line, whether it is an optional test, the requirements it cites and the design property it names if any.
+2. THE Document_Summary for `tasks.md` SHALL carry none of a task's detail bullets and SHALL quote nothing else from the document.
+
+### Requirement 5: A revision shows what changed
+
+**User Story:** As an Author who asked for changes, I want to see plainly what changed in the document, so that I can check my request was understood without rereading the whole file.
+
+#### Acceptance Criteria
+
+1. WHEN the Author answers `Changes needed` and the Skill has revised the Spec_Document, THE Skill SHALL show a Revision_Summary and put the Approval_Question again, in that order and in the same message.
+2. THE Revision_Summary SHALL open with the Spec_Document's path and SHALL list one line per section that changed, saying what changed in it; a section that did not change SHALL not be listed.
+3. IF part of the Author's change request was not applied, THEN THE Revision_Summary SHALL say which part and why, before the Approval_Question.
+4. THE Revision_Summary SHALL quote a Highlight that changed, a user story or a Key_Decision, and SHALL otherwise say what changed without reproducing the Spec_Document's body.
+
+### Requirement 6: The skill text and the README agree
+
+**User Story:** As a reader of the Skill or the README, I want them to describe the hand-back as it now works, so that neither promises a full print the Skill no longer makes.
+
+#### Acceptance Criteria
+
+1. THE Hand_Backs_Bullet SHALL say that on Spec_Route the Skill hands back each Spec_Document as its path and a Document_Summary, and a revision as a Revision_Summary.
+2. THE Skill's steps that write the three Spec_Documents SHALL each say to show the Document_Summary at the depth Requirements 2, 3 and 4 set for that document, and the Skill SHALL hold the shape of the Revision_Summary once, where the three steps can refer to it.
+3. THE README's row for the Skill SHALL say that the Author sees each document's path and a summary and approves each before the next.
+4. THE System SHALL change no skill, agent or rule beyond what Requirements 1 to 7 and 8.1 name.
+
+### Requirement 7: An eval proves the shape
+
+**User Story:** As a maintainer, I want an Eval_Case that reaches a written Spec_Document and grades its hand-back, so that the change is proven by behaviour rather than by reading the skill text.
+
+#### Acceptance Criteria
+
+1. THE System SHALL add one Eval_Case that gives the Skill a request on the calc fixture with the spec questions answered in the request, so that the run writes `requirements.md` and ends at its Approval_Question.
+2. THE Eval_Case SHALL grade that `requirements.md` was written in the Spec_Folder, at `.freethinking/specs/*/requirements.md`, that the final message names its path, that it does not reproduce the document's sections, that it quotes a user story, that no criterion is reproduced, and that every entry quotes its user story; whether there is one entry per requirement is read by the wave reviewer and by the first real spec written with the Skill, since a grader that sees only the reply cannot count the document's requirements.
+3. THE Eval_Case SHALL pass `make validate` and carry the `start-task` tag so `make eval-skill-start-task` selects it.
+4. THE System SHALL run `make eval-skill-start-task` after the change, and SHALL record the result table in the pull request's Testing section, with every existing case still passing.
+
+### Requirement 8: Specs live under `.freethinking/specs/`
+
+**User Story:** As a maintainer of the plugin and its forks, I want every spec to live in the Spec_Folder, `.freethinking/specs//`, instead of `.claude/specs//`, so that the folder names the plugin rather than one tool, a fork for another tool keeps the same path, and the eval sandbox, which refuses every write under `.claude/`, can grade a spec being written. GitHub issue #48 is the ticket.
+
+#### Acceptance Criteria
+
+1. THE start-task Skill, THE implement-spec Skill, THE task-executor agent, THE workflow Rule and THE README SHALL name the Spec_Folder wherever they name `.claude/specs//` today, and THE README's "Tune the plugin for a repository" section SHALL say that `.freethinking/specs/` holds specs beside the `/.md` overrides.
+2. THE root README SHALL name the Spec_Folder where it names the old folder.
+3. THE Eval_Cases SHALL plant, name and grade the Spec_Folder wherever they plant, name or grade `.claude/specs/` today, their fixture folders moved with `git mv`, and `evals/README.md` SHALL replace its note that edits under `.claude/` cannot be graded with one saying the Spec_Folder is writable in the sandbox while `.claude/` is not.
+4. THE System SHALL move this repository's spec records from `.claude/specs/` to `.freethinking/specs/` with `git mv`, content untouched, this spec included.
+5. IF the sandbox refuses a write under `.freethinking/` too, THEN THE System SHALL stop and report it, since the folder would then need another name.
diff --git a/.freethinking/specs/spec-approval-summary/tasks.md b/.freethinking/specs/spec-approval-summary/tasks.md
new file mode 100644
index 0000000..9bc4b39
--- /dev/null
+++ b/.freethinking/specs/spec-approval-summary/tasks.md
@@ -0,0 +1,57 @@
+# Implementation Plan
+
+## Overview
+
+The skill text comes first, since the README row and the eval case both describe what it says. The README row and the eval case follow in one wave, touching disjoint files. The spec folder move, found necessary when the eval sandbox refused the write under `.claude/`, is one wave of three tasks on disjoint file groups. The last wave is the author's: the eval runs that cost tokens, with the table for the pull request. Each task is proved by `make validate` plus the ephemeral check its text names; the eval run is the integration proof. GitHub issue #47 is the ticket.
+
+## Tasks
+
+- [x] 1. Change the start-task skill's hand-back
+ - In `plugins/freethinking/skills/start-task/SKILL.md`, make the five edits of the design's SKILL.md section, each quoted there as it will read: the Hand-backs bullet; the new "Showing a document" section after "Working with the author" and before step 1, with its two paragraphs; the resume sentence in step 1; the closing paragraph of steps 4, 5 and 6, each saying its summary's depth and the Showing a document section, with the AskUserQuestion sentence kept as it is; and nothing else. Ephemeral check: `grep -c 'in full' SKILL.md` is 0, `grep -c 'Showing a document' SKILL.md` is 6 (the heading, the Hand-backs bullet, step 1 and the three steps), the Approve question's header, options and wording are unchanged by `git diff`; `make validate` passes
+ - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.1, 2.2, 2.3, 3.1, 3.2, 3.3, 3.4, 4.1, 4.2, 5.1, 5.2, 5.3, 5.4, 6.1, 6.2, 6.4_
+
+- [x] 2. Update the README row
+ - In `plugins/freethinking/README.md`, replace the last clause of the `start-task` row, "with you approving each document before the next", with "showing you each document as its path and a short summary and asking you to approve it before the next", as the design's README section gives it; `make validate` passes, which runs `checks/test_descriptions.py`
+ - _Requirements: 6.3_
+
+- [x] 3. Add the eval case
+ - Create `evals/skills/start-task/summarises-requirements/` as the design's eval section lays it out: `case.yaml` naming `scaffold.sh`; `scaffold.sh` as a regular executable file that finds the repository root and runs `evals/fixtures/setup.sh calc main`; `prompt.md` with the frontmatter fields and the prompt quoted in the design; and the eight graders of the design's table, `writes-requirements`, `names-the-path`, `not-reprinted`, `offers-approval`, `quotes-a-user-story`, `no-criteria-reproduced`, `every-entry-quotes-a-story` and `no-code-written`, each with the type and fields the table gives. Ephemeral check: run the scaffold by hand in an empty directory as `evals/README.md` shows and confirm `calc/ops.py` and `tests/test_ops.py` exist on `main`; `make validate` passes, which runs `checks/test_eval_cases.py`
+ - _Requirements: 7.1, 7.2, 7.3_
+
+- [x] 4. Run the start-task evals
+ - The author runs `make eval-skill-start-task EVAL_ARGS="--runs 1 --case summarises-requirements"` to iterate the new case, fixing a grader or the skill text as the design's error-handling rows say, then `make eval-skill-start-task` at the default three runs, and pastes the table into the pull request's Testing section with every existing case still passing
+ - **Property 1: A document is never printed for approval**
+ - **Validates: Requirements 7.4, 1.1, 1.2, 1.4, 2.2**
+
+- [x] 5. Move the spec folder in the plugin text
+ - In `plugins/freethinking/skills/start-task/SKILL.md`, `plugins/freethinking/skills/implement-spec/SKILL.md`, `plugins/freethinking/agents/task-executor.md`, `plugins/freethinking/rules/workflow.md` and `plugins/freethinking/README.md`, replace `.claude/specs` with `.freethinking/specs`; add the "Tune the plugin" sentence the design's move table gives; replace the path in the root `README.md`. Ephemeral check: `grep -r '\.claude/specs' plugins/ README.md` finds nothing; `make validate` passes
+ - _Requirements: 8.1, 8.2_
+
+- [x] 6. Move the spec folder in the evals
+ - `git mv` the four `files/.claude/specs` fixture folders to `files/.freethinking/specs`; replace `.claude/specs` with `.freethinking/specs` in every prompt, grader, scaffold and case README under `evals/`; rewrite the sandbox note in `evals/README.md` as the design's move table gives it. Ephemeral check: `grep -r '\.claude/specs' evals` finds nothing; the `works-one-wave` and `closed-spec-is-a-record` scaffolds run by hand in an empty directory plant the spec at the new path; `make validate` passes
+ - _Requirements: 8.3_
+
+- [x] 7. Move the records
+ - `git mv .claude/specs .freethinking/specs`, the untracked `spec-approval-summary` folder moving with the directory; `git status` shows renames and the untracked folder at the new path only, and `.claude/settings.json` stays
+ - _Requirements: 8.4_
+
+## Notes
+
+- Every task runs `make validate` before it is done; an ephemeral check is created in a scratch location and deleted afterwards.
+- Tasks 1 and 5 are the only edits to the skill; the executor quotes the design's text as given and changes no other sentence, so the four existing start-task cases stay the regression check.
+- Task 4 is the author's, since the eval runs cost tokens; it gets no sub-agent.
+- The `report` skill's templates, the `pr` skill and `bugfix` are not touched, beyond the path replacement of task 5 where one of them names the spec folder.
+- After task 7 this spec lives at `.freethinking/specs/spec-approval-summary/`; ticks after that go there.
+
+## Task Dependency Graph
+
+```json
+{
+ "waves": [
+ { "id": 0, "tasks": ["1"] },
+ { "id": 1, "tasks": ["2", "3"] },
+ { "id": 2, "tasks": ["5", "6", "7"] },
+ { "id": 3, "tasks": ["4"] }
+ ]
+}
+```
diff --git a/.claude/specs/standalone-task-routing/design.md b/.freethinking/specs/standalone-task-routing/design.md
similarity index 100%
rename from .claude/specs/standalone-task-routing/design.md
rename to .freethinking/specs/standalone-task-routing/design.md
diff --git a/.claude/specs/standalone-task-routing/requirements.md b/.freethinking/specs/standalone-task-routing/requirements.md
similarity index 100%
rename from .claude/specs/standalone-task-routing/requirements.md
rename to .freethinking/specs/standalone-task-routing/requirements.md
diff --git a/.claude/specs/standalone-task-routing/tasks.md b/.freethinking/specs/standalone-task-routing/tasks.md
similarity index 100%
rename from .claude/specs/standalone-task-routing/tasks.md
rename to .freethinking/specs/standalone-task-routing/tasks.md
diff --git a/.claude/specs/task-executor-agent/design.md b/.freethinking/specs/task-executor-agent/design.md
similarity index 100%
rename from .claude/specs/task-executor-agent/design.md
rename to .freethinking/specs/task-executor-agent/design.md
diff --git a/.claude/specs/task-executor-agent/requirements.md b/.freethinking/specs/task-executor-agent/requirements.md
similarity index 100%
rename from .claude/specs/task-executor-agent/requirements.md
rename to .freethinking/specs/task-executor-agent/requirements.md
diff --git a/.claude/specs/task-executor-agent/tasks.md b/.freethinking/specs/task-executor-agent/tasks.md
similarity index 100%
rename from .claude/specs/task-executor-agent/tasks.md
rename to .freethinking/specs/task-executor-agent/tasks.md
diff --git a/.claude/specs/workflow-rule-wording/design.md b/.freethinking/specs/workflow-rule-wording/design.md
similarity index 100%
rename from .claude/specs/workflow-rule-wording/design.md
rename to .freethinking/specs/workflow-rule-wording/design.md
diff --git a/.claude/specs/workflow-rule-wording/requirements.md b/.freethinking/specs/workflow-rule-wording/requirements.md
similarity index 100%
rename from .claude/specs/workflow-rule-wording/requirements.md
rename to .freethinking/specs/workflow-rule-wording/requirements.md
diff --git a/.claude/specs/workflow-rule-wording/tasks.md b/.freethinking/specs/workflow-rule-wording/tasks.md
similarity index 100%
rename from .claude/specs/workflow-rule-wording/tasks.md
rename to .freethinking/specs/workflow-rule-wording/tasks.md
diff --git a/README.md b/README.md
index 6b7e105..b45c533 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@ its free checks and its spec records. To install and use the plugin, read
plugin directory scans every file in that folder when the plugin is
submitted.
- `checks/`: the free unit tests.
-- `.claude/specs/`: the design records of past tasks.
+- `.freethinking/specs/`: the design records of past tasks.
- `.claude-plugin/marketplace.json`: the marketplace entry that points at the
plugin folder.
diff --git a/evals/README.md b/evals/README.md
index c43daeb..8b3bde9 100644
--- a/evals/README.md
+++ b/evals/README.md
@@ -151,10 +151,11 @@ the worked example.
files and git state only; nothing it writes is loaded as configuration.
- The harness puts the workspace's git status into the session context at
start, so a skill can know the branch and dirty state without running git.
-- Edits to files under `.claude/` in the workspace are refused even when Edit
- is granted, and so is a shell fallback. A skill that writes there (ticking a
- spec's task list) cannot be graded on that write; grade the rest and expect
- the skill to report the refusal.
+- Writes and edits under `.claude/` in the workspace are refused even when
+ Write or Edit is granted, and so is a shell fallback; a path-scoped grant such
+ as `Write(.claude/**)` does not lift it, and a committed `CLAUDE.md` is not
+ loaded. Specs live under `.freethinking/specs/`, which the sandbox lets a
+ skill write, so a spec being written or ticked can be graded there.
- A prompt that starts with `/freethinking:` is expanded before the model
runs, so a `tool_used` grader on `Skill` never fires for it; grade the
behaviour instead. A Skill call the model makes later, to another skill, is
diff --git a/evals/rules/workflow/closed-spec-is-a-record/files/.claude/specs/calc-subtract/design.md b/evals/rules/workflow/closed-spec-is-a-record/files/.freethinking/specs/calc-subtract/design.md
similarity index 100%
rename from evals/rules/workflow/closed-spec-is-a-record/files/.claude/specs/calc-subtract/design.md
rename to evals/rules/workflow/closed-spec-is-a-record/files/.freethinking/specs/calc-subtract/design.md
diff --git a/evals/rules/workflow/closed-spec-is-a-record/files/.claude/specs/calc-subtract/requirements.md b/evals/rules/workflow/closed-spec-is-a-record/files/.freethinking/specs/calc-subtract/requirements.md
similarity index 100%
rename from evals/rules/workflow/closed-spec-is-a-record/files/.claude/specs/calc-subtract/requirements.md
rename to evals/rules/workflow/closed-spec-is-a-record/files/.freethinking/specs/calc-subtract/requirements.md
diff --git a/evals/rules/workflow/closed-spec-is-a-record/files/.claude/specs/calc-subtract/tasks.md b/evals/rules/workflow/closed-spec-is-a-record/files/.freethinking/specs/calc-subtract/tasks.md
similarity index 100%
rename from evals/rules/workflow/closed-spec-is-a-record/files/.claude/specs/calc-subtract/tasks.md
rename to evals/rules/workflow/closed-spec-is-a-record/files/.freethinking/specs/calc-subtract/tasks.md
diff --git a/evals/rules/workflow/closed-spec-is-a-record/prompt.md b/evals/rules/workflow/closed-spec-is-a-record/prompt.md
index 5b96199..e208d55 100644
--- a/evals/rules/workflow/closed-spec-is-a-record/prompt.md
+++ b/evals/rules/workflow/closed-spec-is-a-record/prompt.md
@@ -3,6 +3,6 @@ description: A request on an area whose only spec is closed takes the route the
tags: [rule, workflow]
max_turns: 10
allowed_tools: [Read, Glob, Grep, Skill]
-expected_outcome: Claude reads .claude/specs/calc-subtract/ as a record of merged work, since every task is ticked, subtract is already in calc/ops.py and the prompt says its branch merged, and does not invoke /freethinking:implement-spec. The request is a new change, so /freethinking:start-task is invoked, proposes a route for divide and asks the author which to take. Nothing is written.
+expected_outcome: Claude reads .freethinking/specs/calc-subtract/ as a record of merged work, since every task is ticked, subtract is already in calc/ops.py and the prompt says its branch merged, and does not invoke /freethinking:implement-spec. The request is a new change, so /freethinking:start-task is invoked, proposes a route for divide and asks the author which to take. Nothing is written.
---
-Add divide(a, b) to calc/ops.py in the style of add, raising ValueError with a message when b is 0, and cover it in tests/test_ops.py. An earlier task left a spec in .claude/specs/calc-subtract/; its branch merged.
+Add divide(a, b) to calc/ops.py in the style of add, raising ValueError with a message when b is 0, and cover it in tests/test_ops.py. An earlier task left a spec in .freethinking/specs/calc-subtract/; its branch merged.
diff --git a/evals/rules/workflow/closed-spec-is-a-record/scaffold.sh b/evals/rules/workflow/closed-spec-is-a-record/scaffold.sh
index 3aa7f8c..c5b89f3 100755
--- a/evals/rules/workflow/closed-spec-is-a-record/scaffold.sh
+++ b/evals/rules/workflow/closed-spec-is-a-record/scaffold.sh
@@ -1,7 +1,7 @@
#!/usr/bin/env bash
# Builds the workspace for this case: the calc fixture on main with subtract
# already in calc/ops.py and tested, and the calc-subtract spec from
-# files/.claude/specs/ with every task ticked, so the spec reads as merged
+# files/.freethinking/specs/ with every task ticked, so the spec reads as merged
# work. The files are copied in before the setup script runs so that its one
# commit holds them, and a file at a fixture path, calc/ops.py and
# tests/test_ops.py here, replaces the fixture's copy. No wrappers: the case
diff --git a/evals/rules/workflow/spec-routes-to-implement-spec/prompt.md b/evals/rules/workflow/spec-routes-to-implement-spec/prompt.md
index fd474b4..856bc4c 100644
--- a/evals/rules/workflow/spec-routes-to-implement-spec/prompt.md
+++ b/evals/rules/workflow/spec-routes-to-implement-spec/prompt.md
@@ -5,4 +5,4 @@ max_turns: 10
allowed_tools: [Read, Glob, Grep, Skill]
expected_outcome: Claude invokes /freethinking:implement-spec (the Skill tool) rather than reading the spec and coding straight away. The sandbox has no spec, so the skill then stops; only the routing is graded.
---
-There is an approved spec in .claude/specs/link-shortener/ with a tasks.md. Pick up the work and continue it.
+There is an approved spec in .freethinking/specs/link-shortener/ with a tasks.md. Pick up the work and continue it.
diff --git a/evals/skills/implement-spec/invalid-graph-stops/prompt.md b/evals/skills/implement-spec/invalid-graph-stops/prompt.md
index 904386b..b8c24d6 100644
--- a/evals/skills/implement-spec/invalid-graph-stops/prompt.md
+++ b/evals/skills/implement-spec/invalid-graph-stops/prompt.md
@@ -3,6 +3,6 @@ description: Invoked on a spec whose Task Dependency Graph omits a leaf task, im
tags: [skill, implement-spec]
max_turns: 8
allowed_tools: [Read, Glob, Grep]
-expected_outcome: Claude reads `.claude/specs/link-shortener/`, finds that leaf task 4.2 is missing from the graph, proposes a corrected `waves` block that includes 4.2, and stops for approval. It writes nothing.
+expected_outcome: Claude reads `.freethinking/specs/link-shortener/`, finds that leaf task 4.2 is missing from the graph, proposes a corrected `waves` block that includes 4.2, and stops for approval. It writes nothing.
---
/freethinking:implement-spec link-shortener
diff --git a/evals/skills/implement-spec/invalid-graph-stops/scaffold.sh b/evals/skills/implement-spec/invalid-graph-stops/scaffold.sh
index 39e9714..703eb88 100755
--- a/evals/skills/implement-spec/invalid-graph-stops/scaffold.sh
+++ b/evals/skills/implement-spec/invalid-graph-stops/scaffold.sh
@@ -3,9 +3,9 @@
# Task Dependency Graph omits leaf task 4.2. Runs in the empty eval workspace.
set -euo pipefail
-mkdir -p .claude/specs/link-shortener
+mkdir -p .freethinking/specs/link-shortener
-cat > .claude/specs/link-shortener/requirements.md <<'MD'
+cat > .freethinking/specs/link-shortener/requirements.md <<'MD'
# Requirements Document
## Introduction
@@ -31,7 +31,7 @@ A link shortener: users submit a long URL and get a short code; visiting the cod
2. WHEN a short code has no visits, THE Service SHALL report 0.
MD
-cat > .claude/specs/link-shortener/design.md <<'MD'
+cat > .freethinking/specs/link-shortener/design.md <<'MD'
# Design Document
## Overview
@@ -63,7 +63,7 @@ The count never decreases and equals the number of visits recorded.
Unit tests with the link store mocked; property tests with at least 100 iterations per property.
MD
-cat > .claude/specs/link-shortener/tasks.md <<'MD'
+cat > .freethinking/specs/link-shortener/tasks.md <<'MD'
# Implementation Plan
## Overview
diff --git a/evals/skills/implement-spec/no-spec-recommends-start-task/prompt.md b/evals/skills/implement-spec/no-spec-recommends-start-task/prompt.md
index 2325777..f97815c 100644
--- a/evals/skills/implement-spec/no-spec-recommends-start-task/prompt.md
+++ b/evals/skills/implement-spec/no-spec-recommends-start-task/prompt.md
@@ -2,6 +2,6 @@
description: Invoked on a task that has no spec, implement-spec says so and recommends start-task instead of building anything.
tags: [skill, implement-spec]
max_turns: 6
-expected_outcome: Claude finds no `.claude/specs/link-shortener/tasks.md`, says the spec does not exist, and recommends `/freethinking:start-task`. It writes nothing.
+expected_outcome: Claude finds no `.freethinking/specs/link-shortener/tasks.md`, says the spec does not exist, and recommends `/freethinking:start-task`. It writes nothing.
---
/freethinking:implement-spec link-shortener
diff --git a/evals/skills/implement-spec/offers-choice-on-discovery/README.md b/evals/skills/implement-spec/offers-choice-on-discovery/README.md
index 94738c8..e3f1377 100644
--- a/evals/skills/implement-spec/offers-choice-on-discovery/README.md
+++ b/evals/skills/implement-spec/offers-choice-on-discovery/README.md
@@ -10,7 +10,7 @@ choose. The executor reports it under `unsure` and does not fix it unasked.
The works-one-wave workspace: the calc package from `evals/fixtures/calc/` on
branch `calc-subtract`, with the two-wave spec under
-`.claude/specs/calc-subtract/` committed, and the `bin/` wrappers the
+`.freethinking/specs/calc-subtract/` committed, and the `bin/` wrappers the
Makefile's implement-spec target puts on the PATH. The one difference is
`files/tests/test_ops.py`. A file at a fixture path replaces the fixture's
copy, because `evals/fixtures/setup.sh` copies a fixture file only where the
diff --git a/evals/skills/implement-spec/offers-choice-on-discovery/files/.claude/specs/calc-subtract/design.md b/evals/skills/implement-spec/offers-choice-on-discovery/files/.freethinking/specs/calc-subtract/design.md
similarity index 100%
rename from evals/skills/implement-spec/offers-choice-on-discovery/files/.claude/specs/calc-subtract/design.md
rename to evals/skills/implement-spec/offers-choice-on-discovery/files/.freethinking/specs/calc-subtract/design.md
diff --git a/evals/skills/implement-spec/offers-choice-on-discovery/files/.claude/specs/calc-subtract/requirements.md b/evals/skills/implement-spec/offers-choice-on-discovery/files/.freethinking/specs/calc-subtract/requirements.md
similarity index 100%
rename from evals/skills/implement-spec/offers-choice-on-discovery/files/.claude/specs/calc-subtract/requirements.md
rename to evals/skills/implement-spec/offers-choice-on-discovery/files/.freethinking/specs/calc-subtract/requirements.md
diff --git a/evals/skills/implement-spec/offers-choice-on-discovery/files/.claude/specs/calc-subtract/tasks.md b/evals/skills/implement-spec/offers-choice-on-discovery/files/.freethinking/specs/calc-subtract/tasks.md
similarity index 100%
rename from evals/skills/implement-spec/offers-choice-on-discovery/files/.claude/specs/calc-subtract/tasks.md
rename to evals/skills/implement-spec/offers-choice-on-discovery/files/.freethinking/specs/calc-subtract/tasks.md
diff --git a/evals/skills/implement-spec/works-all-waves/README.md b/evals/skills/implement-spec/works-all-waves/README.md
index 9278116..d0a98ce 100644
--- a/evals/skills/implement-spec/works-all-waves/README.md
+++ b/evals/skills/implement-spec/works-all-waves/README.md
@@ -11,7 +11,7 @@ also carries the `Final review of the run:` line.
## What the scaffold builds
The same workspace as works-one-wave: a small Python package on branch
-`calc-subtract` with a committed spec under `.claude/specs/calc-subtract/`,
+`calc-subtract` with a committed spec under `.freethinking/specs/calc-subtract/`,
two tasks in two waves (add `subtract`, then test it). The package is
`evals/fixtures/calc/`, built by `evals/fixtures/setup.sh`; the spec is this
case's `files/` folder, a copy of works-one-wave's, copied in before that
@@ -36,6 +36,8 @@ each wave report and the final report by invoking the Skill tool with
- `adds-subtract`: `calc/ops.py` contains the function task 1 describes.
- `works-wave-1`: `tests/test_ops.py` gained `test_subtract`, so wave 1 ran
without a hand-back after wave 0. works-one-wave grades the opposite.
+- `ticks-both-tasks`: `.freethinking/specs/calc-subtract/tasks.md` has
+ `- [x] 1.` and then `- [x] 2.`, so both waves were ticked.
- `reports-every-wave`: the final report carries the wave review line of
wave 1, so the report covers each wave and not only the first.
- `reviews-the-run`: the final report carries the final review's verdict, so
@@ -53,11 +55,10 @@ each wave report and the final report by invoking the Skill tool with
## What it cannot check
-The ticks, for the reason works-one-wave gives: inside an eval run, Claude
-Code refuses edits under `.claude/`, so each tick is denied and the skill is
-expected to say so. At spec cadence that refusal must not end the run early;
-if it does, `works-wave-1` and `reviews-the-run` fail, and the transcript
-shows the hand-back after wave 0.
+Whether each tick came after its wave review: the graders read the file at
+the end of the run, not when it changed. At spec cadence a tick must not end
+the run early; if it does, `works-wave-1` and `reviews-the-run` fail, and the
+transcript shows the hand-back after wave 0.
## Running it
diff --git a/evals/skills/implement-spec/works-all-waves/files/.claude/specs/calc-subtract/design.md b/evals/skills/implement-spec/works-all-waves/files/.freethinking/specs/calc-subtract/design.md
similarity index 100%
rename from evals/skills/implement-spec/works-all-waves/files/.claude/specs/calc-subtract/design.md
rename to evals/skills/implement-spec/works-all-waves/files/.freethinking/specs/calc-subtract/design.md
diff --git a/evals/skills/implement-spec/works-all-waves/files/.claude/specs/calc-subtract/requirements.md b/evals/skills/implement-spec/works-all-waves/files/.freethinking/specs/calc-subtract/requirements.md
similarity index 100%
rename from evals/skills/implement-spec/works-all-waves/files/.claude/specs/calc-subtract/requirements.md
rename to evals/skills/implement-spec/works-all-waves/files/.freethinking/specs/calc-subtract/requirements.md
diff --git a/evals/skills/implement-spec/works-all-waves/files/.claude/specs/calc-subtract/tasks.md b/evals/skills/implement-spec/works-all-waves/files/.freethinking/specs/calc-subtract/tasks.md
similarity index 100%
rename from evals/skills/implement-spec/works-all-waves/files/.claude/specs/calc-subtract/tasks.md
rename to evals/skills/implement-spec/works-all-waves/files/.freethinking/specs/calc-subtract/tasks.md
diff --git a/evals/skills/implement-spec/works-all-waves/graders/ticks-both-tasks.md b/evals/skills/implement-spec/works-all-waves/graders/ticks-both-tasks.md
new file mode 100644
index 0000000..79e0f5a
--- /dev/null
+++ b/evals/skills/implement-spec/works-all-waves/graders/ticks-both-tasks.md
@@ -0,0 +1,5 @@
+---
+type: regex
+pattern: '- \[x\] 1\.[\s\S]*- \[x\] 2\.'
+target: { source: file, path: .freethinking/specs/calc-subtract/tasks.md }
+---
diff --git a/evals/skills/implement-spec/works-all-waves/prompt.md b/evals/skills/implement-spec/works-all-waves/prompt.md
index 3d37992..d8c081e 100644
--- a/evals/skills/implement-spec/works-all-waves/prompt.md
+++ b/evals/skills/implement-spec/works-all-waves/prompt.md
@@ -3,8 +3,8 @@ description: On a scaffolded project with a committed two-wave spec, implement-s
tags: [skill, implement-spec]
max_turns: 70
allowed_tools: [Read, Glob, Grep, Agent, Skill]
-expected_outcome: Claude validates the graph, launches the task-executor agent for task 1, runs the tests itself, launches the wave-reviewer agent for wave 0, writes the wave's report and starts wave 1 without waiting, does the same for task 2, then launches the wave-reviewer agent once more over the whole run and hands back with a final report carrying a Wave review line for each wave and the `Final review of the run:` line. It writes each wave report and the final report inline with the report skill, each opening with `## Problems` or `No problems.` before `## Done`. Its attempts to tick the tasks are refused, because the sandbox denies edits under .claude/, and it says so rather than working around it.
+expected_outcome: Claude validates the graph, launches the task-executor agent for task 1, runs the tests itself, launches the wave-reviewer agent for wave 0, writes the wave's report and starts wave 1 without waiting, does the same for task 2, then launches the wave-reviewer agent once more over the whole run and hands back with a final report carrying a Wave review line for each wave and the `Final review of the run:` line. It writes each wave report and the final report inline with the report skill, each opening with `## Problems` or `No problems.` before `## Done`. It ticks each task in tasks.md as its checks pass, which the sandbox should now allow.
---
/freethinking:implement-spec calc-subtract spec
-I will not be able to answer questions during this run. Cadence: spec, run every wave and hand back only at the end. There are no optional tests. The branch is already calc-subtract. This sandbox refuses edits under .claude/, so if ticking a task in tasks.md is refused, say so in the report and carry on to the next wave as if it were ticked.
+I will not be able to answer questions during this run. Cadence: spec, run every wave and hand back only at the end. There are no optional tests. The branch is already calc-subtract.
diff --git a/evals/skills/implement-spec/works-all-waves/scaffold.sh b/evals/skills/implement-spec/works-all-waves/scaffold.sh
index bd522f2..3290622 100755
--- a/evals/skills/implement-spec/works-all-waves/scaffold.sh
+++ b/evals/skills/implement-spec/works-all-waves/scaffold.sh
@@ -1,6 +1,6 @@
#!/usr/bin/env bash
# Builds the workspace for this case: the calc fixture on branch calc-subtract
-# with the two-wave spec from files/.claude/specs/calc-subtract/ committed
+# with the two-wave spec from files/.freethinking/specs/calc-subtract/ committed
# alongside it, and the bin wrappers the Makefile's implement-spec target puts
# on the PATH. The spec is copied in before the setup script runs so that its
# one commit holds it, on main and on the branch.
diff --git a/evals/skills/implement-spec/works-one-wave/README.md b/evals/skills/implement-spec/works-one-wave/README.md
index f80db81..7f5dbe0 100644
--- a/evals/skills/implement-spec/works-one-wave/README.md
+++ b/evals/skills/implement-spec/works-one-wave/README.md
@@ -9,7 +9,7 @@ skill in its handback shape: Problems first, or `No problems.`, then Done.
## What the scaffold builds
A small Python package on branch `calc-subtract` with a committed spec under
-`.claude/specs/calc-subtract/`: two tasks in two waves (add `subtract`, then
+`.freethinking/specs/calc-subtract/`: two tasks in two waves (add `subtract`, then
test it). The package is `evals/fixtures/calc/`, built by
`evals/fixtures/setup.sh`; the spec is this case's `files/` folder, copied in
before that script's one commit. Tests run with `python3 -m unittest`. `bin/`
@@ -31,6 +31,10 @@ writes the hand-back by invoking the Skill tool with `freethinking:report` and
- `adds-subtract`: `calc/ops.py` contains the function task 1 describes.
- `leaves-wave-1`: `tests/test_ops.py` gained no `test_subtract`, so wave 1 was
not started.
+- `ticks-task-1`: `.freethinking/specs/calc-subtract/tasks.md` has `- [x] 1.`,
+ so the tick landed after the wave review.
+- `leaves-task-2-unticked`: the same file still has `- [ ] 2.`, so wave 1 was
+ not ticked either.
- `reviews-the-wave`: the report carries the wave review's verdict, so the
reviewer agent was launched.
- `invokes-report`: the Skill tool was called with the `report` skill, so the
@@ -40,12 +44,9 @@ writes the hand-back by invoking the Skill tool with `freethinking:report` and
## What it cannot check
-The tick. Inside an eval run, Claude Code refuses edits to files under
-`.claude/` even when Edit is granted, so the skill's attempt to tick task 1 is
-denied, as is a shell fallback. The skill is expected to report that and stop,
-which it does; a grader on the tick would only ever test the sandbox. Observed
-on Claude Code 2.1.x; if that changes, add a grader on
-`.claude/specs/calc-subtract/tasks.md` for `[x] 1.`.
+Whether the tick came after the wave review rather than before it: the
+graders read the file at the end of the run, not when it changed. The
+transcript shows the order.
## Running it
diff --git a/evals/skills/implement-spec/works-one-wave/files/.claude/specs/calc-subtract/design.md b/evals/skills/implement-spec/works-one-wave/files/.freethinking/specs/calc-subtract/design.md
similarity index 100%
rename from evals/skills/implement-spec/works-one-wave/files/.claude/specs/calc-subtract/design.md
rename to evals/skills/implement-spec/works-one-wave/files/.freethinking/specs/calc-subtract/design.md
diff --git a/evals/skills/implement-spec/works-one-wave/files/.claude/specs/calc-subtract/requirements.md b/evals/skills/implement-spec/works-one-wave/files/.freethinking/specs/calc-subtract/requirements.md
similarity index 100%
rename from evals/skills/implement-spec/works-one-wave/files/.claude/specs/calc-subtract/requirements.md
rename to evals/skills/implement-spec/works-one-wave/files/.freethinking/specs/calc-subtract/requirements.md
diff --git a/evals/skills/implement-spec/works-one-wave/files/.claude/specs/calc-subtract/tasks.md b/evals/skills/implement-spec/works-one-wave/files/.freethinking/specs/calc-subtract/tasks.md
similarity index 100%
rename from evals/skills/implement-spec/works-one-wave/files/.claude/specs/calc-subtract/tasks.md
rename to evals/skills/implement-spec/works-one-wave/files/.freethinking/specs/calc-subtract/tasks.md
diff --git a/evals/skills/implement-spec/works-one-wave/graders/leaves-task-2-unticked.md b/evals/skills/implement-spec/works-one-wave/graders/leaves-task-2-unticked.md
new file mode 100644
index 0000000..a39774e
--- /dev/null
+++ b/evals/skills/implement-spec/works-one-wave/graders/leaves-task-2-unticked.md
@@ -0,0 +1,5 @@
+---
+type: regex
+pattern: '- \[ \] 2\.'
+target: { source: file, path: .freethinking/specs/calc-subtract/tasks.md }
+---
diff --git a/evals/skills/implement-spec/works-one-wave/graders/ticks-task-1.md b/evals/skills/implement-spec/works-one-wave/graders/ticks-task-1.md
new file mode 100644
index 0000000..7ef2185
--- /dev/null
+++ b/evals/skills/implement-spec/works-one-wave/graders/ticks-task-1.md
@@ -0,0 +1,5 @@
+---
+type: regex
+pattern: '- \[x\] 1\.'
+target: { source: file, path: .freethinking/specs/calc-subtract/tasks.md }
+---
diff --git a/evals/skills/implement-spec/works-one-wave/prompt.md b/evals/skills/implement-spec/works-one-wave/prompt.md
index b3eb5eb..445461d 100644
--- a/evals/skills/implement-spec/works-one-wave/prompt.md
+++ b/evals/skills/implement-spec/works-one-wave/prompt.md
@@ -3,7 +3,7 @@ description: On a scaffolded project with a committed two-wave spec, implement-s
tags: [skill, implement-spec]
max_turns: 40
allowed_tools: [Read, Glob, Grep, Agent, Skill]
-expected_outcome: Claude validates the graph, launches the task-executor agent for task 1, runs the tests itself, launches the wave-reviewer agent once for the wave and reports its verdict, and leaves wave 1 alone (no test_subtract written). It writes the hand-back inline with the report skill, and the Message opens with `## Problems` or `No problems.` before `## Done`, and keeps the `Wave review of wave n:` line under Checks. It also tries to tick task 1 and is refused, because the sandbox denies edits under .claude/, and says so rather than working around it.
+expected_outcome: Claude validates the graph, launches the task-executor agent for task 1, runs the tests itself, launches the wave-reviewer agent once for the wave and reports its verdict, and leaves wave 1 alone (no test_subtract written). It writes the hand-back inline with the report skill, and the Message opens with `## Problems` or `No problems.` before `## Done`, and keeps the `Wave review of wave n:` line under Checks. It also ticks task 1 in tasks.md, which the sandbox should now allow.
---
/freethinking:implement-spec calc-subtract wave
diff --git a/evals/skills/implement-spec/works-one-wave/scaffold.sh b/evals/skills/implement-spec/works-one-wave/scaffold.sh
index bd522f2..3290622 100755
--- a/evals/skills/implement-spec/works-one-wave/scaffold.sh
+++ b/evals/skills/implement-spec/works-one-wave/scaffold.sh
@@ -1,6 +1,6 @@
#!/usr/bin/env bash
# Builds the workspace for this case: the calc fixture on branch calc-subtract
-# with the two-wave spec from files/.claude/specs/calc-subtract/ committed
+# with the two-wave spec from files/.freethinking/specs/calc-subtract/ committed
# alongside it, and the bin wrappers the Makefile's implement-spec target puts
# on the PATH. The spec is copied in before the setup script runs so that its
# one commit holds it, on main and on the branch.
diff --git a/evals/skills/start-task/bug-offers-bugfix/graders/no-spec-written.md b/evals/skills/start-task/bug-offers-bugfix/graders/no-spec-written.md
index 7a79050..9d64c9d 100644
--- a/evals/skills/start-task/bug-offers-bugfix/graders/no-spec-written.md
+++ b/evals/skills/start-task/bug-offers-bugfix/graders/no-spec-written.md
@@ -1,5 +1,5 @@
---
type: file_exists
-path: '.claude/specs/**'
+path: '.freethinking/specs/**'
exists: false
---
diff --git a/evals/skills/start-task/bug-offers-bugfix/prompt.md b/evals/skills/start-task/bug-offers-bugfix/prompt.md
index 7ae6a1a..648a402 100644
--- a/evals/skills/start-task/bug-offers-bugfix/prompt.md
+++ b/evals/skills/start-task/bug-offers-bugfix/prompt.md
@@ -3,6 +3,6 @@ description: Invoked directly with observed versus intended behaviour that never
tags: [skill, start-task]
max_turns: 6
allowed_tools: [Read, Glob, Grep, Agent, Skill]
-expected_outcome: Claude reads calc/ops.py and tests/test_ops.py, states in two or three sentences that this is a bug and takes Bug_Route, naming add in calc/ops.py returning a - b, and asks the author which route to take, with Bug_Route and Spec_Route as options on their own lines. It launches no sub-agent, invokes no skill, writes nothing under .claude/specs/, and leaves calc/ops.py unchanged.
+expected_outcome: Claude reads calc/ops.py and tests/test_ops.py, states in two or three sentences that this is a bug and takes Bug_Route, naming add in calc/ops.py returning a - b, and asks the author which route to take, with Bug_Route and Spec_Route as options on their own lines. It launches no sub-agent, invokes no skill, writes nothing under .freethinking/specs/, and leaves calc/ops.py unchanged.
---
/freethinking:start-task calc.add(2, 3) returns -1; it should return 5
diff --git a/evals/skills/start-task/contained-change-offers-executor/graders/no-spec-written.md b/evals/skills/start-task/contained-change-offers-executor/graders/no-spec-written.md
index 7a79050..9d64c9d 100644
--- a/evals/skills/start-task/contained-change-offers-executor/graders/no-spec-written.md
+++ b/evals/skills/start-task/contained-change-offers-executor/graders/no-spec-written.md
@@ -1,5 +1,5 @@
---
type: file_exists
-path: '.claude/specs/**'
+path: '.freethinking/specs/**'
exists: false
---
diff --git a/evals/skills/start-task/contained-change-offers-executor/prompt.md b/evals/skills/start-task/contained-change-offers-executor/prompt.md
index dbfa9b8..1be2993 100644
--- a/evals/skills/start-task/contained-change-offers-executor/prompt.md
+++ b/evals/skills/start-task/contained-change-offers-executor/prompt.md
@@ -3,6 +3,6 @@ description: Given a contained change against the calc fixture, start-task triag
tags: [skill, start-task]
max_turns: 6
allowed_tools: [Read, Glob, Grep, Agent, Skill]
-expected_outcome: Claude reads calc/ops.py and the tests, says in two or three sentences that adding subtract next to add is a contained change taking Executor_Route, naming the code it touches, proposes `subtract` (or similar) as the task name and a branch name, and asks the route question with Executor_Route (Recommended) and Spec_Route as options. It writes nothing under .claude/specs/, edits no code, and launches no sub-agent or skill.
+expected_outcome: Claude reads calc/ops.py and the tests, says in two or three sentences that adding subtract next to add is a contained change taking Executor_Route, naming the code it touches, proposes `subtract` (or similar) as the task name and a branch name, and asks the route question with Executor_Route (Recommended) and Spec_Route as options. It writes nothing under .freethinking/specs/, edits no code, and launches no sub-agent or skill.
---
/freethinking:start-task Add subtract(a, b) to calc/ops.py returning a minus b, in the style of add
diff --git a/evals/skills/start-task/names-task-and-asks/graders/no-spec-written.md b/evals/skills/start-task/names-task-and-asks/graders/no-spec-written.md
index 7a79050..9d64c9d 100644
--- a/evals/skills/start-task/names-task-and-asks/graders/no-spec-written.md
+++ b/evals/skills/start-task/names-task-and-asks/graders/no-spec-written.md
@@ -1,5 +1,5 @@
---
type: file_exists
-path: '.claude/specs/**'
+path: '.freethinking/specs/**'
exists: false
---
diff --git a/evals/skills/start-task/names-task-and-asks/prompt.md b/evals/skills/start-task/names-task-and-asks/prompt.md
index 03845fa..ef87d20 100644
--- a/evals/skills/start-task/names-task-and-asks/prompt.md
+++ b/evals/skills/start-task/names-task-and-asks/prompt.md
@@ -3,6 +3,6 @@ description: Given a request that extends the calc fixture, start-task proposes
tags: [skill, start-task]
max_turns: 6
allowed_tools: [Read, Glob, Grep, Agent, Skill]
-expected_outcome: Claude reads the calc fixture, proposes `calculation-history` (or a similar kebab-case name) and a branch name, says in one sentence that the request takes Spec_Route, and asks its spec questions in prose. It writes nothing under .claude/specs/ and edits no code.
+expected_outcome: Claude reads the calc fixture, proposes `calculation-history` (or a similar kebab-case name) and a branch name, says in one sentence that the request takes Spec_Route, and asks its spec questions in prose. It writes nothing under .freethinking/specs/ and edits no code.
---
/freethinking:start-task Keep a history of every calculation: record each operation with its operands and result as it runs, and add a way to list the history.
diff --git a/evals/skills/start-task/summarises-requirements/case.yaml b/evals/skills/start-task/summarises-requirements/case.yaml
new file mode 100644
index 0000000..a9121e1
--- /dev/null
+++ b/evals/skills/start-task/summarises-requirements/case.yaml
@@ -0,0 +1,4 @@
+schema_version: "1.1"
+name: summarises-requirements
+context:
+ scaffold_script: scaffold.sh
diff --git a/evals/skills/start-task/summarises-requirements/graders/every-entry-quotes-a-story.md b/evals/skills/start-task/summarises-requirements/graders/every-entry-quotes-a-story.md
new file mode 100644
index 0000000..d25ce80
--- /dev/null
+++ b/evals/skills/start-task/summarises-requirements/graders/every-entry-quotes-a-story.md
@@ -0,0 +1,13 @@
+---
+type: llm
+---
+
+The reply is start-task's hand-back of the requirements.md it wrote for a calculation-history feature on a small calc package, ending with the approval question; the judge sees only the reply, not the file.
+
+Check only these two things, and nothing else.
+1. Before the approval options, the reply has a list with one item per requirement, and every item quotes a user story: text that begins "As a" and contains "I want" and "so that".
+2. The reply does not print a section of the document: there is no heading or block such as Introduction, Glossary or Acceptance Criteria, and no numbered list of criteria.
+
+PASS when both hold. FAIL when either does not.
+
+Allowed, and never a reason to fail: a short summary sentence after a quoted story; a bracketed reference such as (2.2); a list of decisions or open questions after the items; bold or backticks anywhere; the approval options written in plain text.
diff --git a/evals/skills/start-task/summarises-requirements/graders/names-the-path.md b/evals/skills/start-task/summarises-requirements/graders/names-the-path.md
new file mode 100644
index 0000000..12a8c39
--- /dev/null
+++ b/evals/skills/start-task/summarises-requirements/graders/names-the-path.md
@@ -0,0 +1,4 @@
+---
+type: regex
+pattern: '\.freethinking/specs/[a-z0-9-]+/requirements\.md'
+---
diff --git a/evals/skills/start-task/summarises-requirements/graders/no-code-written.md b/evals/skills/start-task/summarises-requirements/graders/no-code-written.md
new file mode 100644
index 0000000..a5605a0
--- /dev/null
+++ b/evals/skills/start-task/summarises-requirements/graders/no-code-written.md
@@ -0,0 +1,5 @@
+---
+type: file_exists
+path: '**/*.py'
+exists: false
+---
diff --git a/evals/skills/start-task/summarises-requirements/graders/no-criteria-reproduced.md b/evals/skills/start-task/summarises-requirements/graders/no-criteria-reproduced.md
new file mode 100644
index 0000000..ae2f482
--- /dev/null
+++ b/evals/skills/start-task/summarises-requirements/graders/no-criteria-reproduced.md
@@ -0,0 +1,5 @@
+---
+type: regex
+pattern: '\bSHALL\b'
+match: not_contains
+---
diff --git a/evals/skills/start-task/summarises-requirements/graders/not-reprinted.md b/evals/skills/start-task/summarises-requirements/graders/not-reprinted.md
new file mode 100644
index 0000000..37f5233
--- /dev/null
+++ b/evals/skills/start-task/summarises-requirements/graders/not-reprinted.md
@@ -0,0 +1,6 @@
+---
+type: regex
+pattern: '^#+\s*Acceptance Criteria|^## Glossary'
+match: not_contains
+flags: m
+---
diff --git a/evals/skills/start-task/summarises-requirements/graders/offers-approval.md b/evals/skills/start-task/summarises-requirements/graders/offers-approval.md
new file mode 100644
index 0000000..6e1ac0d
--- /dev/null
+++ b/evals/skills/start-task/summarises-requirements/graders/offers-approval.md
@@ -0,0 +1,5 @@
+---
+type: regex
+pattern: '^\s*(?:[-*•]|\d+[.)])\s*[*_`]*Approved\b'
+flags: im
+---
diff --git a/evals/skills/start-task/summarises-requirements/graders/quotes-a-user-story.md b/evals/skills/start-task/summarises-requirements/graders/quotes-a-user-story.md
new file mode 100644
index 0000000..c674d12
--- /dev/null
+++ b/evals/skills/start-task/summarises-requirements/graders/quotes-a-user-story.md
@@ -0,0 +1,4 @@
+---
+type: regex
+pattern: 'As an? .+, I want'
+---
diff --git a/evals/skills/start-task/summarises-requirements/graders/writes-requirements.md b/evals/skills/start-task/summarises-requirements/graders/writes-requirements.md
new file mode 100644
index 0000000..9e47367
--- /dev/null
+++ b/evals/skills/start-task/summarises-requirements/graders/writes-requirements.md
@@ -0,0 +1,5 @@
+---
+type: file_exists
+path: '.freethinking/specs/*/requirements.md'
+exists: true
+---
diff --git a/evals/skills/start-task/summarises-requirements/prompt.md b/evals/skills/start-task/summarises-requirements/prompt.md
new file mode 100644
index 0000000..0b2eddd
--- /dev/null
+++ b/evals/skills/start-task/summarises-requirements/prompt.md
@@ -0,0 +1,8 @@
+---
+description: With the spec questions answered in the request, start-task writes requirements.md for the calc fixture and hands it back as its path and one entry per requirement with its user story quoted, anything it decided listed as an open question, not the text, then asks for approval. Needs the Makefile's skill target, which grants Write and Edit and runs the scaffold.
+tags: [skill, start-task]
+max_turns: 12
+allowed_tools: [Read, Glob, Grep, Write, Edit, Agent, Skill]
+expected_outcome: With the spec questions answered in the request, Claude writes requirements.md under .freethinking/specs/ for the calc fixture and hands it back as its path and one entry per requirement with its user story quoted, not the text, then asks for approval. The final message names the path, gives one entry per requirement with its user story quoted, lists anything the skill decided as an open question, quotes no acceptance criterion, reprints no section of the document, offers Approved and Changes needed, and Claude writes no code.
+---
+/freethinking:start-task Keep a history of every calculation: record each operation with its operands and result as it runs, and add a way to list the history. Answers to the spec questions: it is for a developer using the calc package from a script, so they can see afterwards what was computed and in what order; out of scope is keeping the history beyond the process or sharing it between processes, and clearing the history; no constraints beyond the standard library and the existing tests passing; keep it in a new module that wraps the operations, so only calls made through it are recorded, and record a call that raises as an entry holding the error instead of a result. I will not answer further questions in this run: decide anything else yourself and list it as an open question in the hand-back.
diff --git a/evals/skills/start-task/summarises-requirements/scaffold.sh b/evals/skills/start-task/summarises-requirements/scaffold.sh
new file mode 100755
index 0000000..73e9c0c
--- /dev/null
+++ b/evals/skills/start-task/summarises-requirements/scaffold.sh
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Builds the workspace for this case: the calc fixture on main, with no spec
+# files, so start-task has code to read and a spec folder to write.
+set -euo pipefail
+ROOT=$(git -C "$(dirname "$0")" rev-parse --show-toplevel)
+bash "$ROOT/evals/fixtures/setup.sh" calc main
diff --git a/evals/skills/start-task/wrong-repo-asks-fit/graders/no-spec-written.md b/evals/skills/start-task/wrong-repo-asks-fit/graders/no-spec-written.md
index 7a79050..9d64c9d 100644
--- a/evals/skills/start-task/wrong-repo-asks-fit/graders/no-spec-written.md
+++ b/evals/skills/start-task/wrong-repo-asks-fit/graders/no-spec-written.md
@@ -1,5 +1,5 @@
---
type: file_exists
-path: '.claude/specs/**'
+path: '.freethinking/specs/**'
exists: false
---
diff --git a/evals/skills/start-task/wrong-repo-asks-fit/prompt.md b/evals/skills/start-task/wrong-repo-asks-fit/prompt.md
index 1f5054b..6680c83 100644
--- a/evals/skills/start-task/wrong-repo-asks-fit/prompt.md
+++ b/evals/skills/start-task/wrong-repo-asks-fit/prompt.md
@@ -3,6 +3,6 @@ description: Given a request that extends nothing in the calc fixture, start-tas
tags: [skill, start-task]
max_turns: 6
allowed_tools: [Read, Glob, Grep, Agent, Skill]
-expected_outcome: Claude reads the calc fixture, says in two or three sentences that a link shortener extends nothing in it (no module, pattern or test it builds on), and asks the fit question with Spec it here and Wrong repository as options, before any spec question. The route statement with the task name comes first in the same message as the Fit question. It writes nothing under .claude/specs/, edits no code, and launches no sub-agent or skill.
+expected_outcome: Claude reads the calc fixture, says in two or three sentences that a link shortener extends nothing in it (no module, pattern or test it builds on), and asks the fit question with Spec it here and Wrong repository as options, before any spec question. The route statement with the task name comes first in the same message as the Fit question. It writes nothing under .freethinking/specs/, edits no code, and launches no sub-agent or skill.
---
/freethinking:start-task Link shortener: users submit a long URL and get a short code; visiting the code redirects and counts the click
diff --git a/plugins/freethinking/.claude-plugin/plugin.json b/plugins/freethinking/.claude-plugin/plugin.json
index 21ea374..a49ea50 100644
--- a/plugins/freethinking/.claude-plugin/plugin.json
+++ b/plugins/freethinking/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "freethinking",
"displayName": "Freethinking",
- "version": "0.13.0",
+ "version": "0.14.0",
"description": "Shared engineering skills: standard workflows and prompts for day-to-day development.",
"author": {
"name": "FreeThinking IT",
diff --git a/plugins/freethinking/README.md b/plugins/freethinking/README.md
index 7dc5ca8..5c5241f 100644
--- a/plugins/freethinking/README.md
+++ b/plugins/freethinking/README.md
@@ -30,11 +30,16 @@ To update by hand:
claude plugin update freethinking@freethinkingit
```
+Specs moved from `.claude/specs/` to `.freethinking/specs/` in 0.14.0. In a
+repository with specs under the old folder, run
+`git mv .claude/specs .freethinking/specs` once: `start-task` and
+`implement-spec` look only in the new folder.
+
## Skills
| Skill | Run it with | What it does |
| ----- | ----------- | ------------ |
-| `start-task` | `/freethinking:start-task `, or ask Claude to change something, or to start or spec a task | The front door for any change: reads the code the request touches, then sends one contained change to the `task-executor` agent, a defect to `bugfix` and everything else to a spec, asking you before taking either of the first two. On the spec route, writes `requirements.md`, `design.md` and `tasks.md` in `.claude/specs//` before any code, following the team template, with you approving each document before the next. |
+| `start-task` | `/freethinking:start-task `, or ask Claude to change something, or to start or spec a task | The front door for any change: reads the code the request touches, then sends one contained change to the `task-executor` agent, a defect to `bugfix` and everything else to a spec, asking you before taking either of the first two. On the spec route, writes `requirements.md`, `design.md` and `tasks.md` in `.freethinking/specs//` before any code, following the team template, showing you each document as its path and a short summary and asking you to approve it before the next. |
| `implement-spec` | `/freethinking:implement-spec [task] [task\|wave\|spec]`, or ask Claude to implement, build or continue a spec | Builds a task from its approved spec, wave by wave from `tasks.md`, each leaf task in its own sub-agent, ticking a task only once its tests pass, running the full suite at the end of every wave, and handing back to you after each task, after each wave, or only once every wave is done (with a short report after each wave and a final review of the whole run), whichever you chose. Each discovery outside the task in hand is listed with its size and the choice between a task and an issue. Pauses with a proposal when the design cannot be followed, and hands off to `pr` when the spec is done. |
| `bugfix` | `/freethinking:bugfix [what you already know]`, or ask Claude to fix a bug | Reads the ticket, and anything you already know that you put after it, reproduces the bug before touching code, confirms the root cause with you, fixes the cause with a regression test, verifies the fix, then hands off to `pr` or leaves its findings on the ticket. |
| `pr` | `/freethinking:pr [ticket] [base-branch]`, or ask Claude to open a PR | Takes the ticket as its first argument and reads it, offers to create the branch and commit if needed, walks the branch's changes with you one at a time with a short set of review prompts, drafts the title and description from your answers, and opens the PR with `gh` once you approve. Needs the `gh` CLI signed in. |
@@ -114,18 +119,21 @@ changes come from a spec wave.
A repository can keep its own versions of the plugin's template files in a
`.freethinking/` folder at its root, laid out as `/.md`, such as
-`.freethinking/report/handback.md`. A file there replaces the plugin's file of
-the same name whole; nothing is merged. Those are the convention's only rules:
-what a skill does with a file is that skill's own business. This release
-applies the convention to the `report` skill's templates, one per mode. The
-`report` skill
-reads them as shapes to write in and ignores any action a template asks for,
-as its own text says. A repository's `handback.md` may use its own sections:
-`implement-spec` reads a wave report by what it holds, problems, what was done,
-checks, files and the next step, and the plugin's own evals grade only the
-plugin's template, so renaming sections costs nothing but the two verdict lines
-being found by content rather than by name. The spec templates of `start-task` and the default
-pull request template of `pr` are candidates to move there later.
+`.freethinking/report/handback.md`. The same folder holds the specs:
+`start-task` writes each task's three documents to
+`.freethinking/specs//`, and `implement-spec` reads them there. A file
+under a `/` folder replaces the plugin's file of the same name whole;
+nothing is merged. Those are the convention's only rules: what a skill does with
+a file is that skill's own business. This release applies the convention to the
+`report` skill's templates, one per mode. The `report` skill reads them as
+shapes to write in and ignores any action a template asks for, as its own text
+says. A repository's `handback.md` may use its own sections: `implement-spec`
+reads a wave report by what it holds, problems, what was done, checks, files and
+the next step, and the plugin's own evals grade only the plugin's template, so
+renaming sections costs nothing but the two verdict lines being found by content
+rather than by name. The spec templates of `start-task` and the default pull
+request template of `pr` are candidates to move under `.freethinking//`
+later.
## What the plugin runs and sends
@@ -147,6 +155,6 @@ plugin's `rules/` folder.
No skill, agent or hook reads a credential, runs a package launcher or sends
anything anywhere else.
-The source repository's `evals/` and `.claude/specs/` folders are its test
+The source repository's `evals/` and `.freethinking/specs/` folders are its test
suite and its design records. They sit outside the plugin, and an installed
plugin never runs them.
diff --git a/plugins/freethinking/agents/task-executor.md b/plugins/freethinking/agents/task-executor.md
index 072078c..7cb41bb 100644
--- a/plugins/freethinking/agents/task-executor.md
+++ b/plugins/freethinking/agents/task-executor.md
@@ -19,7 +19,7 @@ Decide the mode from the launch prompt alone, before anything else.
- **Spec mode**: the prompt says the task comes from a spec, in any words; implement-spec says "This task is a leaf task from a spec; tests are tasks of their own." There, tests are tasks of their own: write a test only when your task's text asks for one, tag it with the design property the prompt names if it names one, and produce no code for any task but your own.
- **Standalone mode**: the prompt does not say that. The ordinary rule applies: the change comes with its test, written the way the project writes tests. When the project has no test framework, say so in the Summary and record a manual check instead; do not add one.
-Nothing else sets the mode: not a `.claude/specs/` directory in the repository, not the shape of the task.
+Nothing else sets the mode: not a `.freethinking/specs/` directory in the repository, not the shape of the task.
## Procedure
diff --git a/plugins/freethinking/rules/workflow.md b/plugins/freethinking/rules/workflow.md
index 25b7450..991543e 100644
--- a/plugins/freethinking/rules/workflow.md
+++ b/plugins/freethinking/rules/workflow.md
@@ -8,5 +8,5 @@ These rules say how a request finds the handbook skill that does it. They apply
The rest hold in every session, skill or no skill.
- **Never work on the default branch.** Create a branch before the first commit. Do not commit or push unless the author asks; a yes to an offer a skill raised counts as asking.
-- **A merged spec is a record.** `.claude/specs//` holds the task's three spec files and nothing else. Once its tasks are ticked and its branch merged, the spec is closed: it is not work in hand for implement-spec, it is not edited to match later code, and it is not read to learn how the code works today. Current behaviour lives in the code and the repository's own documentation.
+- **A merged spec is a record.** `.freethinking/specs//` holds the task's three spec files and nothing else. Once its tasks are ticked and its branch merged, the spec is closed: it is not work in hand for implement-spec, it is not edited to match later code, and it is not read to learn how the code works today. Current behaviour lives in the code and the repository's own documentation.
- **Keep the author in the loop.** When the approach changes, or a step turns out to be bigger than expected, say so before carrying on. Ask only what the code and the request cannot answer, and batch the questions.
diff --git a/plugins/freethinking/skills/implement-spec/SKILL.md b/plugins/freethinking/skills/implement-spec/SKILL.md
index 91d64e9..4d1f80a 100644
--- a/plugins/freethinking/skills/implement-spec/SKILL.md
+++ b/plugins/freethinking/skills/implement-spec/SKILL.md
@@ -1,13 +1,13 @@
---
name: implement-spec
-description: Build a task whose spec already exists, wave by wave from its tasks.md, with the task-executor agent building each task and the wave-reviewer agent reading each wave. Use when asked to implement, build, work, continue or resume a spec, a task list, or the tasks in .claude/specs//. Reads the spec and validates its dependency graph, then asks once how often to hand back (after each task, each wave, or only at the end) and how to treat optional tests (ask, always, never). Runs one sub-agent per leaf task, ticks a checkbox only when its tests pass or a stated manual check is done, and runs the full suite at the end of every wave. Never edits the spec beyond checkboxes without the author's approval, and pauses with a proposal when the design cannot be followed.
+description: Build a task whose spec already exists, wave by wave from its tasks.md, with the task-executor agent building each task and the wave-reviewer agent reading each wave. Use when asked to implement, build, work, continue or resume a spec, a task list, or the tasks in .freethinking/specs//. Reads the spec and validates its dependency graph, then asks once how often to hand back (after each task, each wave, or only at the end) and how to treat optional tests (ask, always, never). Runs one sub-agent per leaf task, ticks a checkbox only when its tests pass or a stated manual check is done, and runs the full suite at the end of every wave. Never edits the spec beyond checkboxes without the author's approval, and pauses with a proposal when the design cannot be followed.
argument-hint: "[task-name] [task|wave|spec]"
-allowed-tools: Bash(git status *) Bash(git branch *) Bash(git rev-parse *) Bash(git log *) Bash(git diff *) Bash(ls .claude/specs*) Bash(cat .claude/specs/*)
+allowed-tools: Bash(git status *) Bash(git branch *) Bash(git rev-parse *) Bash(git log *) Bash(git diff *) Bash(ls .freethinking/specs*) Bash(cat .freethinking/specs/*)
---
# Implement a spec
-Build a task from its approved spec: read `.claude/specs//`, check that its task list can be executed, and then work the waves in order, each leaf task built by its own executor and each wave read by the reviewer before the wave ends, ticking each checkbox only when its tests have passed or, for a task with nothing to test, after a stated manual check. Hand back to the author as often as they chose, after every task, after every wave, or only once every wave is done, with a report of what was built and tested.
+Build a task from its approved spec: read `.freethinking/specs//`, check that its task list can be executed, and then work the waves in order, each leaf task built by its own executor and each wave read by the reviewer before the wave ends, ticking each checkbox only when its tests have passed or, for a task with nothing to test, after a stated manual check. Hand back to the author as often as they chose, after every task, after every wave, or only once every wave is done, with a report of what was built and tested.
The author is accountable for the code and owns the spec. The spec is the source of truth: `requirements.md` says what, `design.md` says how, and `tasks.md` says in what order. Do not change any of them, beyond ticking checkboxes, without the author's approval, and do not guess your way past a design that cannot be followed; pause and propose the change instead.
@@ -40,10 +40,10 @@ Terms used below:
Take the task name from the arguments: the first word that is not `task`, `wave` or `spec`. The cadence is a second argument of `task`, `wave` or `spec`, or an explicit phrase in the author's message such as "one task at a time", "a wave at a time" or "run all the waves". The word "task" or "spec" on its own in a sentence is not a cadence. The optional-tests choice is settled here only by an explicit phrase in the author's message, such as "skip the optional tests".
-- With a task name, the spec is `.claude/specs//`.
-- With no task name, run `ls .claude/specs/*/tasks.md` and look at each list for an unticked non-optional leaf task. Exactly one such spec: name it and proceed. Several: list them and ask which to work. None: say there is nothing to implement, name any spec whose only unticked tasks are optional tests, recommend `/freethinking:start-task` otherwise, and stop.
+- With a task name, the spec is `.freethinking/specs//`.
+- With no task name, run `ls .freethinking/specs/*/tasks.md` and look at each list for an unticked non-optional leaf task. Exactly one such spec: name it and proceed. Several: list them and ask which to work. None: say there is nothing to implement, name any spec whose only unticked tasks are optional tests, recommend `/freethinking:start-task` otherwise, and stop.
-If the spec has no `tasks.md`, say so, recommend `/freethinking:start-task`, and stop without changing anything. One look at `.claude/specs//tasks.md` settles it; do not search elsewhere for the spec.
+If the spec has no `tasks.md`, say so, recommend `/freethinking:start-task`, and stop without changing anything. One look at `.freethinking/specs//tasks.md` settles it; do not search elsewhere for the spec.
Read `tasks.md`, `requirements.md` and `design.md` in full before anything else. The requirements and design are read again task by task later, but the whole has to be in view first.
diff --git a/plugins/freethinking/skills/start-task/SKILL.md b/plugins/freethinking/skills/start-task/SKILL.md
index bb80b5a..bea06c1 100644
--- a/plugins/freethinking/skills/start-task/SKILL.md
+++ b/plugins/freethinking/skills/start-task/SKILL.md
@@ -1,6 +1,6 @@
---
name: start-task
-description: Front door for any request to change code. Reads the code the request touches, then decides whether it goes to the task executor, to the bugfix skill or to a spec, and asks the author when the answer is not a spec. Start a new feature or task by writing its spec before any code. Use for any request to change code that no other skill takes (not a bug the author named, which is bugfix's; not an existing spec, which is implement-spec's; not a pull request, which is pr's; and not a typo-sized change, which needs no skill), and when asked to start, plan, spec, scope or design a task, feature or piece of work, or when a request is big enough that coding straight away would be guessing. Produces requirements.md, design.md and tasks.md in .claude/specs//, following the team's spec template, with the author approving each document before the next is written. Does not write code.
+description: Front door for any request to change code. Reads the code the request touches, then decides whether it goes to the task executor, to the bugfix skill or to a spec, and asks the author when the answer is not a spec. Start a new feature or task by writing its spec before any code. Use for any request to change code that no other skill takes (not a bug the author named, which is bugfix's; not an existing spec, which is implement-spec's; not a pull request, which is pr's; and not a typo-sized change, which needs no skill), and when asked to start, plan, spec, scope or design a task, feature or piece of work, or when a request is big enough that coding straight away would be guessing. Produces requirements.md, design.md and tasks.md in .freethinking/specs//, following the team's spec template, with the author approving each document before the next is written. Does not write code.
argument-hint: "[task name or short description]"
---
@@ -22,14 +22,20 @@ Task, as the author gave it: $ARGUMENTS
- **Stops.** The route question at triage, when the route is Bug_Route or Executor_Route; the fit question at triage, when the request extends nothing in the codebase; the approval of each of the three documents on Spec_Route; the relaunch question after a `stopped` Summary on Executor_Route.
- **How it asks.** With the AskUserQuestion tool, fixed options plus free text, at every stop. The spec questions at the head of the requirements step are the exception: ask them in prose, because the answers are the author's own words.
-- **Hand-backs.** On Executor_Route, the executor's Summary verbatim and the diff, failures first, then the closing Message written with `report`. On Spec_Route, each document in full.
+- **Hand-backs.** On Executor_Route, the executor's Summary verbatim and the diff, failures first, then the closing Message written with `report`. On Spec_Route, each document as its path and a summary, and each revision as its path and what changed, as the Showing a document section says.
- **Hand-offs.** `bugfix` on Bug_Route; `pr` after a `done` Summary; `implement-spec` after `tasks.md` is approved. The branch name proposed in step 1 is created by the author before the first commit, or by `implement-spec` at its set-up when the author gives it that name, or by `pr` at its branch offer, under the name `pr` proposes from the ticket, which is the same shape when the author passes the ticket to it; never by this skill.
+## Showing a document
+
+A document is shown for approval as its path and a summary, never as its whole text: the author opens the file to read it. The summary and the approval question go in one message, the summary first. The summary opens with the document's path from the repository root on its own line, says once that the author can open the file before answering, then gives the document's content in the shape the step that wrote it sets, quoting from the document only what that shape names and summarising the rest in plain words.
+
+After `Changes needed`, revise the file, then show it again as its path and one line per section that changed, saying what changed in it and quoting a user story or key decision that changed; a section that did not change is not listed. If part of the request was not applied, say which part and why. The revision and the step's approval question go in one message, the revision first.
+
## 1. Name the task and find its spec
-Derive a kebab-case task name from the request, for example `link-shortener`. Beside it, propose a branch name: the issue number and the task name, such as `12-link-shortener`, when the request names or links an issue, and the task name alone otherwise. Do not create the branch. Say both in the route statement of step 3, so the author can correct them in the same breath. The spec lives in `.claude/specs//` in the current repository.
+Derive a kebab-case task name from the request, for example `link-shortener`. Beside it, propose a branch name: the issue number and the task name, such as `12-link-shortener`, when the request names or links an issue, and the task name alone otherwise. Do not create the branch. Say both in the route statement of step 3, so the author can correct them in the same breath. The spec lives in `.freethinking/specs//` in the current repository.
-If that directory already exists, the request takes Spec_Route without triage, since its size was already decided. Read what is there and resume at the first document that is missing or that the author says is not approved. Do not overwrite an existing document without asking.
+If that directory already exists, the request takes Spec_Route without triage, since its size was already decided. Read what is there and resume at the first document that is missing or that the author says is not approved; if that document exists, it is shown as the Showing a document section says, then its step's approval question is put. Do not overwrite an existing document without asking.
## 2. Read the code
@@ -43,7 +49,7 @@ Before asking any spec question or writing any document, decide which route the
- **Executor_Route** when the request is a contained change: one change, describable in a sentence or two, touching a place in the code you can name after reading it, needing no design decision and no new dependency, framework or tool.
- **Spec_Route** for every other request.
-State the route you chose and the reason for it in two or three sentences that name the code you read; on Spec_Route, one sentence that names the route is enough.
+State the route you chose, by its name as written here, Bug_Route, Executor_Route or Spec_Route, and the reason for it in two or three sentences that name the code you read; on Spec_Route, one sentence that names the route is enough.
If step 2 found nothing the request would extend, no module, pattern or test it builds on, say so in the route statement, which still names the task and branch from step 1; then, before any other question and in the same message as that statement, put one question with the AskUserQuestion tool, header `Fit`, with two options in this order: `Spec it here`, to write the spec in this repository anyway, and `Wrong repository`, to stop, each with a one-sentence description. Act only on the author's answer. On `Wrong repository`, say where the work belongs if the request or the code says, then stop and write nothing. On `Spec it here`, go on with the route, asking the route question after this one when the route has one, since there is no point sizing work that does not belong here.
@@ -90,13 +96,13 @@ Ask the author only what you still need, in one round, in prose:
- Constraints: deadlines, compatibility, performance, security, systems it must work with.
- Anything the author already knows they want or do not want in the solution.
-Then read `${CLAUDE_SKILL_DIR}/spec-template/requirements.md` and write `.claude/specs//requirements.md` with:
+Then read `${CLAUDE_SKILL_DIR}/spec-template/requirements.md` and write `.freethinking/specs//requirements.md` with:
- **Introduction**: what the feature is, who uses it, what value it delivers. A short paragraph. No implementation detail.
- **Glossary**: every domain noun the requirements use, each defined in one sentence, in `Term_Name` form. Use the terms verbatim in the criteria.
- **Requirements**: numbered, each with a user story ("As a ROLE, I want CAPABILITY, so that BENEFIT") and acceptance criteria in EARS form: ubiquitous (`THE System SHALL`), event-driven (`WHEN ..., THE System SHALL`), state-driven (`WHILE ..., THE System SHALL`), optional-feature (`WHERE ..., THE System SHALL`) and unwanted-behaviour (`IF ..., THEN THE System SHALL`). One behaviour per criterion. Quantify what can be quantified. Every requirement covers its unhappy path.
-Then show the author the document and ask with the AskUserQuestion tool, header `Approve`, options `Approved` and `Changes needed`, whether these requirements say what they want built, with anything missing or wrong in the free text. Iterate until approved.
+Then show the document as the Showing a document section says. Its summary is one entry per requirement, in order: the requirement's number and title, then its user story, the requirement's first sentence, quoted; no criterion is quoted and the glossary is not listed. After the entries, name any question the requirements leave open that the author did not answer. Ask with the AskUserQuestion tool, header `Approve`, options `Approved` and `Changes needed`, whether these requirements say what they want built, with anything missing or wrong in the free text. Iterate until approved.
## 5. Write the design
@@ -110,7 +116,7 @@ Read `${CLAUDE_SKILL_DIR}/spec-template/design.md`. Read the parts of the codeba
- **Error Handling**: a table of condition, category, behaviour and requirement.
- **Testing Strategy**: property-based tests for the properties, example and edge-case tests for the error rows, integration tests for the wiring.
-Check traceability both ways before showing it: every requirement is satisfied somewhere in the design, and every decision traces to a requirement. Name anything that does not trace. Then show the author the document and ask with the AskUserQuestion tool, header `Approve`, options `Approved` and `Changes needed`, whether this design is how they want the requirements met, with anything missing or wrong in the free text. Iterate until approved.
+Check traceability both ways before showing it: every requirement is satisfied somewhere in the design, and every decision traces to a requirement. Then show the document as the Showing a document section says. Its summary opens with each key decision quoted, its paragraph, in the document's order, as the things to review, then summarises the rest for discussion: the main flows and design concepts, the parts, what each is for and how the work moves through them, in a few lines, then anything that does not trace. It leaves out the data fields and types, the operations table, the correctness properties, the error-handling rows and the testing strategy. Ask with the AskUserQuestion tool, header `Approve`, options `Approved` and `Changes needed`, whether this design is how they want the requirements met, with anything missing or wrong in the free text. Iterate until approved.
## 6. Write the task list
@@ -121,7 +127,7 @@ Read `${CLAUDE_SKILL_DIR}/spec-template/tasks.md`, then write `tasks.md` with:
- **Notes**: conventions the executor should follow.
- **Task Dependency Graph**: the JSON `waves` block, where each wave depends only on earlier waves. Every leaf task appears exactly once, optional test tasks included. Task numbers only identify tasks; the waves decide the order of execution.
-Then show the author the document and ask with the AskUserQuestion tool, header `Approve`, options `Approved` and `Changes needed`, whether these tasks build the design in an order they accept, with anything missing or wrong in the free text. Iterate until approved.
+Then show the document as the Showing a document section says. Its summary is a table with one row per leaf task in wave order, with columns for the wave, the task's number, what it builds in a line, whether it is an optional test, the requirements it cites and the design property it names if any; none of a task's detail bullets. Ask with the AskUserQuestion tool, header `Approve`, options `Approved` and `Changes needed`, whether these tasks build the design in an order they accept, with anything missing or wrong in the free text. Iterate until approved.
## 7. Hand off