@supersuit/hyperspec 0.2.0 → 0.3.0

package/bin/hyperspec.mjs

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
-import { existsSync, writeFileSync } from "node:fs";
+import { existsSync, statSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import { loadSpec } from "../src/load.mjs";
 import { lintSpec } from "../src/rules.mjs";
 import { score, exitCode } from "../src/score.mjs";
 import { template } from "../src/template.mjs";
+import { writingTemplate } from "../src/writing-template.mjs";
+import { PROFILES, knownProfile } from "../src/profiles.mjs";
 import { readRecipe, checkRecipe } from "../src/recipe.mjs";
 import { approve } from "../src/writer.mjs";
 import { reproduce } from "../src/reproduce.mjs";
@@ -15,6 +18,17 @@ const HELP = `hyperspec <command> [options]
   lint <file...> [--json]      score each hyperspec against the nine tests
                                exit 0 pass, 1 a test fails, 3 blocked on an open decision, 2 usage
   init <file> [--title T] [--kind K]   write a new hyperspec skeleton (refuses to overwrite)
+  init <file> --profile writing [--title T] [--form F] [--fiction]
+                               write a writing-profile skeleton: every required block (materials,
+                               dna, persona, audience, goal, form, spine, sources) shown in full
+                               with placeholder values, dna/persona/audience/goal also carrying an
+                               open decision naming the question only the operator can answer;
+                               --fiction adds one character, same treatment; the skeleton never
+                               passes until its placeholders and open decisions are replaced with
+                               real content; exit 2 for a --profile with no value or one this
+                               linter does not know, --fiction or --form without --profile
+                               writing, --kind with it (use --form), or a folder that does not
+                               exist
 
   recipe check <output-or-recipe> [--json]
                                check a recipe's completeness (a path not ending .recipe.json
@@ -47,11 +61,39 @@ const cmd = argv[0];
 
 if (!cmd || cmd === "--help" || cmd === "-h") { console.log(HELP); process.exit(cmd ? 0 : 2); }
 
+// Each profile that wants its own init skeleton adds one entry here; a profile absent from this
+// map still lints (via PROFILES in profiles.mjs) but init falls back to the plain template for it.
+const PROFILE_TEMPLATES = { writing: writingTemplate };
+
 if (cmd === "init") {
   const file = argv[1];
   if (!file || file.startsWith("--")) { console.error("init needs a file path"); process.exit(2); }
   if (existsSync(file)) { console.error(`refusing to overwrite ${file}`); process.exit(2); }
-  writeFileSync(file, template({ title: flag("--title"), kind: flag("--kind") }));
+  const usage = (msg) => { console.error(msg); process.exit(2); };
+  const given = (name) => argv.includes(name);
+  // A value flag with nothing after it, or another flag after it, has no value.
+  const value = (name) => { const v = flag(name); return v === undefined || v.startsWith("--") ? undefined : v; };
+  const profileName = value("--profile");
+  if (given("--profile") && profileName === undefined) usage("--profile needs a value; known profiles: " + Object.keys(PROFILES).join(", "));
+  if (profileName !== undefined && !knownProfile(profileName)) {
+    usage(`unknown profile: ${profileName}; known profiles: ${Object.keys(PROFILES).join(", ") || "(none)"}`);
+  }
+  const writeTemplate = profileName !== undefined && Object.hasOwn(PROFILE_TEMPLATES, profileName) ? PROFILE_TEMPLATES[profileName] : undefined;
+  // The writing flags mean nothing to the plain template, and --kind means nothing to the writing
+  // one (its kind comes from --form); either would be silently dropped, so both are refused.
+  if (!writeTemplate) {
+    for (const f of ["--fiction", "--form"]) if (given(f)) usage(`${f} only applies with --profile writing`);
+  } else if (given("--kind")) {
+    usage("--kind does not apply with --profile writing; use --form, which sets kind and writing.form.name together");
+  }
+  if (given("--form") && value("--form") === undefined) usage("--form needs a value");
+  const folder = dirname(resolve(file));
+  if (!existsSync(folder) || !statSync(folder).isDirectory()) usage(`the folder ${dirname(file)} does not exist; create it first`);
+  const content = writeTemplate
+    ? writeTemplate({ title: flag("--title"), form: value("--form"), fiction: given("--fiction") })
+    : template({ title: flag("--title"), kind: flag("--kind") });
+  try { writeFileSync(file, content); }
+  catch (e) { usage(`could not write ${file}: ${e.code === "EACCES" ? "permission denied" : e.message}`); }
   console.log(`wrote ${file}; run: hyperspec lint ${file}`);
   process.exit(0);
 }
@@ -79,6 +121,7 @@ if (cmd === "lint") {
   else for (const r of reports) {
     if (r.error) { console.log(`${r.file}: ${r.error}`); continue; }
     console.log(`${r.file}: ${r.status} (${r.passed}/9)${r.open.length ? `, open: ${r.open.join(", ")}` : ""}`);
+    if (r.profile) console.log(`  ${r.profile.name}: ${r.profile.complete}/${r.profile.total} blocks complete`);
     for (const t of r.tests) if (!t.pass) console.log(`  ✗ ${t.n}. ${t.name}`);
     for (const f of r.findings) console.log(`    ${f.severity === "fail" ? "fail" : "warn"} [${f.test}] ${f.message}\n         fix: ${f.fix}`);
   }

package/examples/minimal.hyperspec.md

@@ -7,7 +7,7 @@ decisions:
     state: decided
     value: the operator, reading on a phone
     source: interview A2
-    author: gary-sheng
+    author: example-author
     chosen_by: human
   - id: length
     state: delegated
@@ -22,7 +22,7 @@ requirements:
     check:
       rubric: ask the simulated reader to define the term; pass only on a correct definition
     source: design doc, audience block
-    author: gary-sheng
+    author: example-author
 rejects:
   - hype words about AI
 examples:

package/examples/writing/essay/goldens/close.md

@@ -0,0 +1,2 @@
+So write the three questions on a card. Ask the first one. Then wait, longer than feels polite,
+because the first answer is the one they rehearsed and the second one is the one you came for.

package/examples/writing/essay/goldens/opening.md

@@ -0,0 +1,2 @@
+Your first one-on-one with a new report is the only meeting on your calendar where they should
+set the agenda. Everything else you run. This one you hand over.

package/examples/writing/essay/materials/interview-notes.md

@@ -0,0 +1,12 @@
+Interview notes, a thirty-minute call with an engineering manager of eight years, taken by the
+author during the call. Considered: the manager reviewed these notes afterwards and corrected two
+lines.
+
+- Her rule: the report owns the agenda. She keeps a shared document per person; they add items
+  before the meeting, and she adds hers last, at the bottom.
+- "If I have something urgent, it is not a one-on-one topic. I send it the day it happens."
+- The first one-on-one with a new report is always the same: she asks how they like to receive
+  feedback, in writing or out loud, right away or at the end of the week.
+- Her warning: new managers treat silence as a problem. "Wait. Count to five. The real answer is
+  the second one."
+- She cancels a one-on-one only when the report asks her to, never on her own.

package/examples/writing/essay/materials/team-survey.md

@@ -0,0 +1,7 @@
+Summary of an internal survey the author's team ran in the spring, 41 responses, figures checked
+against the raw export by a second person. Verified.
+
+- 29 of 41 said their most useful one-on-one in the last quarter was one where they brought the
+  first topic.
+- 11 of 41 said at least one of their one-on-ones in the last quarter was mostly project status.
+- The most common free-text request, in 9 responses: "ask me what I want to work on next."

package/examples/writing/essay/materials/voice-memo.md

@@ -0,0 +1,18 @@
+Voice memo transcript, recorded by the author on a walk, lightly cleaned. Raw thinking.
+
+My first one-on-one as a manager was a disaster, and the reason was simple: I ran it. I had a
+list. I went down the list. Project status, blockers, the thing from Tuesday. Thirty minutes
+later my report said "cool, thanks" and left, and I had learned nothing I could not have read in
+the tracker.
+
+What I wish someone had told me: the first one-on-one is the only meeting where they get to set
+the agenda. If you set it, you have told them what the meeting is for, and it is for you.
+
+The three questions I use now. What is taking more of your energy than it should? What do you
+want to be doing more of in six months? What should I stop doing, or start doing, that would
+make your week easier? Then I shut up.
+
+Status goes in the tracker. If a one-on-one is a status meeting, cancel it and read the tracker.
+
+Aside, probably not for this piece: my second manager used to walk the one-on-ones outside. I
+liked it but I do not think it is the point.

package/examples/writing/essay.hyperspec.md

@@ -0,0 +1,217 @@
+---
+hyperspec: "0.1"
+title: Hand your first one-on-one to the person you manage
+kind: essay
+profile: writing
+decisions:
+  - id: kind
+    state: decided
+    value: an essay of 700 to 1,100 words for a newsletter read by people in their first year of managing
+    source: essay/materials/voice-memo.md
+    author: example-author
+    chosen_by: human
+  - id: agenda-card
+    state: decided
+    value: the essay ends on the three questions, written so a reader can copy them onto a card
+    source: essay/materials/voice-memo.md, the three questions
+    author: example-author
+    chosen_by: human
+  - id: publish-venue
+    state: delegated
+    rule: publish where the audience block's reads_on line says the reader already is, and nowhere else
+    source: publishing checklist
+    author: agent:claude
+    chosen_by: agent
+requirements:
+  - id: r1
+    text: the opening line tells the reader who sets the agenda of a first one-on-one
+    fails_when: a reader shown only the first two sentences cannot say who should set the agenda
+    check:
+      rubric: show the simulated reader the first two sentences and ask who sets the agenda; pass only on "the report"
+    source: essay/goldens/opening.md
+    author: example-author
+  - id: r2
+    text: the three questions appear word for word as the voice memo states them
+    fails_when: any of the three questions differs from essay/materials/voice-memo.md by a word
+    check:
+      station: verbatim match of each question against the voice memo
+    source: essay/materials/voice-memo.md
+    author: example-author
+  - id: r3
+    text: every survey figure in the draft matches the verified survey summary
+    fails_when: a figure in the draft has no entry in the claims ledger pointing at essay/materials/team-survey.md, or differs from it
+    check:
+      station: every factual claim in the ledger points at a source span
+    source: sourcing pass
+    author: agent:claude
+  - id: r4
+    text: the draft argues only the four claims in the spine, in order
+    fails_when: a paragraph advances a point that traces to none of c1 to c4, or c3 lands before c2
+    check:
+      rubric: map each paragraph to a spine claim; fail on any paragraph that maps to none or out of order
+    source: spine interview
+    author: example-author
+  - id: r5
+    text: the draft tells the reader what to do with silence in the meeting
+    fails_when: the draft never says to wait after asking a question
+    check:
+      rubric: ask the simulated reader what to do after asking the first question; pass only on "wait"
+    source: essay/materials/interview-notes.md
+    author: example-author
+  - id: r6
+    text: the draft stays inside its length envelope
+    fails_when: the word count is under 700 or over 1,100
+    check:
+      station: word count against form.length
+    source: form decision
+    author: example-author
+rejects:
+  - a list of more than three questions
+  - advice to use the one-on-one for project status
+  - any claim about what most managers do that the survey does not support
+  - the walking one-on-one aside from the voice memo
+examples:
+  - path: essay/goldens/opening.md
+    why: the claim lands in the first sentence, and the second sentence turns it into an instruction
+resume:
+  next_action: mark the three materials into labeled segments, then outline the four spine claims against the form's required parts
+feedback:
+  issues: https://github.com/SupersuitUp/hyperspec/issues
+  fork: MIT; fork it for your own purposes
+improvement:
+  ledger: essay/runs.jsonl
+writing:
+  materials:
+    items:
+      - id: voice-memo
+        path: essay/materials/voice-memo.md
+        produced_by: example-author
+        captured: "2026-09-12"
+        how: voice memo, transcribed
+        trust: raw
+      - id: interview
+        path: essay/materials/interview-notes.md
+        produced_by: example-author
+        captured: "2026-09-15"
+        how: notes taken during a call, reviewed by the person interviewed
+        trust: considered
+      - id: survey
+        path: essay/materials/team-survey.md
+        produced_by: example-author
+        captured: "2026-05-30"
+        how: survey summary, figures checked against the raw export by a second person
+        trust: verified
+    check:
+      station: every segment of every material carries a label from the closed set
+    source: capture step
+    author: agent:claude
+  dna:
+    writer: example-author
+    scope:
+      form: essay
+      audience: new managers
+      purpose: teach
+    rules: style-rules.md
+    goldens:
+      - path: essay/goldens/opening.md
+        why: one plain claim, then a second sentence that turns it into something to do
+      - path: essay/goldens/close.md
+        why: ends on an instruction and gives the reason for it in the same sentence
+    check:
+      rubric: blind lineup within this scope; a judge shown the generated opening beside the two goldens cannot pick it out
+    source: goldens marked on the review page
+    author: example-author
+  persona:
+    identity: self
+    stance: mentor
+    may_assert:
+      - what the author did in their own first one-on-ones and what happened
+      - the three questions the author uses now
+    will_not_say:
+      - a claim about what most managers do, beyond the survey's own figures
+      - the name of anyone on the author's team
+    facts_from: sources
+    check:
+      rubric: persona-consistency judge; the mentor stance holds, and no fact appears that is not in the claims ledger
+    source: persona interview
+    author: example-author
+  audience:
+    who: someone in their first three months of managing, who was promoted from the team they now lead
+    funnel_now: has a first one-on-one with a new report on the calendar this week
+    knows:
+      - one-on-one
+      - report
+      - tracker
+    believes_now: a one-on-one is where a manager catches up on how the work is going
+    wants: a plan for the first meeting that will not waste either person's half hour
+    reads_on: a phone, in the ten minutes before the meeting
+    reader: person
+    check:
+      station: term check against knows; any other term is defined on first use
+      rubric: simulated reader reports where it got lost and where it stopped reading
+    source: audience interview
+    author: example-author
+  goal:
+    from: plans to run the first one-on-one from their own list
+    to: hands the first one-on-one to the report and asks the three questions
+    next_if_worked: copies the three questions into their calendar invite
+    change:
+      kind: action
+      text: the reader asks the three questions in their next one-on-one and waits after each
+    conditions: [r1, r2, r3, r4, r5, r6]
+    check:
+      rubric: the doctor grades the draft against every condition; the simulated reader is asked whether it would copy the questions now
+    source: goal interview
+    author: example-author
+  form:
+    name: essay
+    length:
+      min: 700
+      max: 1100
+      unit: words
+    required_parts:
+      - an opening that states the claim
+      - the story of the author's first one-on-one
+      - the three questions
+      - what to do with the answers
+      - a close the reader can act on
+    stations:
+      - the three questions render as a numbered list
+    check:
+      station: structure and length check against required_parts and length
+    source: form decision
+    author: example-author
+  spine:
+    kind: primer
+    claims:
+      - id: c1
+        text: the first one-on-one is the one meeting where the report should set the agenda
+        materials: [voice-memo, interview]
+      - id: c2
+        text: status belongs in the tracker, and a one-on-one spent on it teaches the manager nothing new
+        materials: [voice-memo, survey]
+      - id: c3
+        text: three questions are enough to hand the meeting over
+        materials: [voice-memo]
+      - id: c4
+        text: the answer worth having comes after a silence the manager does not fill
+        materials: [interview]
+    check:
+      rubric: each claim lands, in order, and the draft argues nothing outside the chain
+    source: spine interview
+    author: example-author
+  sources:
+    ledger: essay/claims.jsonl
+    unsourced_claim: fail
+    check:
+      station: every factual claim in the ledger points at a source span; every quote matches its source verbatim
+    source: sourcing pass
+    author: agent:claude
+fiction: false
+---
+
+# Hand your first one-on-one to the person you manage
+
+A worked example of the writing profile: an essay for new managers, specified before a word of
+it is drafted. Every file this spec names ships beside it. `essay/claims.jsonl` does not exist
+yet, because the claims ledger is written during drafting.

package/examples/writing/story/goldens/dialogue.md

@@ -0,0 +1,3 @@
+"You're late," she said. I wasn't. She knew I wasn't.
+"The bus," I said anyway, because that is how we start.
+"Flour first. Then you can talk."

package/examples/writing/story/goldens/opening.md

@@ -0,0 +1,3 @@
+The alarm at the bakery goes at 3:20, but Ines is always there first, so I have never once
+heard it. What I hear is the mixer. It has a knock in it, a slow one, like it is trying to
+remember something.

package/examples/writing/story/materials/bakery-visit.md

@@ -0,0 +1,8 @@
+Notes from a morning spent at a working bakery, 3:30 to 7:30, with the owner's permission.
+Considered: the owner read these notes and corrected the proofing times.
+
+- First mix at 3:45. Rye sourdough proofs about three hours at room temperature in winter.
+- Trays are turned halfway through the bake because the back left of a deck oven runs hot.
+- The doors open to customers at 7:00. The first person in is usually a regular.
+- The owner does not talk while shaping. Talking happens at the mixer and at the till.
+- Flour is weighed, never scooped. Water temperature is checked every batch.

package/examples/writing/story/materials/notes.md

@@ -0,0 +1,14 @@
+Author's notes for the story, typed over two evenings. Raw thinking.
+
+A bakery on its last morning before the sale closes. Two people: the owner, who has run it for
+thirty-one years, and the apprentice she took on at sixteen, now nineteen. She has not told him
+it is sold. He has not told her he got into a baking school in another city and leaves in the
+autumn. Each thinks they are protecting the other.
+
+The story is four scenes, one morning, 3:40 to 7:00. The oven has a noise. The rye is the thing
+she has never let him do alone.
+
+What it is about, I think: a craft outlives the room it was practiced in. And: people who love
+each other in a work setting say it through the work.
+
+The last line should be about bread, never about feelings.

package/examples/writing/story/materials/scene-list.md

@@ -0,0 +1,7 @@
+Scene list, agreed with the editor before drafting. Considered.
+
+- scene-1, 3:40: Theo arrives. Ines is already mixing. The oven noise. No one says anything real.
+- scene-2, 4:30: shaping. Ines lets Theo shape the rye for the first time, and does not say why.
+- scene-3, 5:50: the bake. Ines tells Theo the bakery is sold, while turning a tray.
+- scene-4, 6:55: before the doors open. Theo tells Ines about the school. She hands him the
+  starter jar.