From 5f55c55d57901ad24fa1b3b7b11d26446d4a5b20 Mon Sep 17 00:00:00 2001 From: shinyobjectz Date: Fri, 20 Nov 2026 13:06:29 -0800 Subject: [PATCH 1/3] PL8: one way to keep work, and any tracker beside it docs/plan.feature PL8: plan.org is the one list, a message isn't a task, closing follows the work, the keywords are the file's, and a task is kept in step with another tracker by :LINK: and #+LINK_STATES:, agreed with raea cloud. @raea/task: trackersOf, trackerStates, keywordFor and statusFor read a task's :LINK: entries (SYSTEM:ID, one per system) and the head's status maps; checkPlan names a bad entry, a URL, a system twice on one task, one tracker item on two tasks and an unknown mapped keyword, each with its fix, and requires nothing else. newPlan takes the keyword sequence its caller keeps. A raea cloud plan.org passes with nothing flagged. --- docs/plan.feature | 72 +++++++++++++++- sdk/task/src/edit.ts | 4 +- sdk/task/src/extend.ts | 6 +- sdk/task/src/index.ts | 1 + sdk/task/src/trackers.ts | 99 ++++++++++++++++++++++ sdk/task/test/trackers.test.ts | 149 +++++++++++++++++++++++++++++++++ 6 files changed, 326 insertions(+), 5 deletions(-) create mode 100644 sdk/task/src/trackers.ts create mode 100644 sdk/task/test/trackers.test.ts diff --git a/docs/plan.feature b/docs/plan.feature index d8099ae8..f4774c78 100644 --- a/docs/plan.feature +++ b/docs/plan.feature @@ -21,7 +21,7 @@ Feature: Plans: a project's plan.org, kept by its agents # src/plan/agent.test.ts driving a turn's plan tools end to end on a faked host; tsc -b clean; e2e todo.spec.ts and # outside.spec.ts (7) and messages, primary, heads, consolidate (26) in Chrome; todo.spec.ts (4) and outside.spec.ts # (3) in raea's window (BLITZ_E2E bundle, node blitz/pw-run.mjs). The board (feed/Board.tsx, board/Lanes.tsx, - # board/CardSheet.tsx) reads the plan now, but no route mounts it. Not done: `raea project new` writes no plan.org yet + # board/CardSheet.tsx), which no route mounted, was removed with PL8: the to-do list is the plan's one view. Not done: `raea project new` writes no plan.org yet # (Rust, engine/cli), so reference/files.md, generated from it, doesn't list one; the page makes it on the first # write. The brief page (BriefView, unmounted) still draws a brief's own ## Tasks. Compositions can't import # @raea/task until sdk/tsconfig.base.json and raea's bundler map it. @@ -140,8 +140,8 @@ Feature: Plans: a project's plan.org, kept by its agents waits on; a critique's gate is " passes check and critique" with :ITEM: the newest critique And an item carries the tags of the tasks linked to it, a workflow field places a channel by its plan's tasks, and a session outside raea holds the tasks whose :AGENT: is @its-name or its inbox - And the board (feed/Board.tsx, board/Lanes.tsx, board/CardSheet.tsx) reads and edits the plan the same way, by - task id; no route mounts it yet + And the to-do list (feed/TodoPanel.tsx) reads and edits the plan the same way, by task id (the board that did + too, never mounted, went with PL8) @done Scenario: PL4c. A brief's tasks move into the plan once @@ -203,6 +203,8 @@ Feature: Plans: a project's plan.org, kept by its agents And none of it uses a dynamic import or dangerouslySetInnerHTML, so raea's window bundle (one IIFE) holds it Rule: PL7. An agent finishes what it planned + # 11-20 (PL8): the keeper's asks (PL7a, PL7b, PL7c, PL7f) are gone. Closing follows the work instead (PL8c), and the + # task per message and the starter task that filled plans with tasks nobody closed are gone too. PL7d and PL7e stay. # Shane, 2026-11-16: "i notice often that it makes tasks but never completes them itself". His plans that morning: # TarotChess's agent posted a first pass and left its own follow-ups TODO (frame rate, a clipping score, a dark # encode); Cadence's said "all six masters are finished and posted" over a plan still saying Track MAKING and Build, @@ -258,3 +260,67 @@ Feature: Plans: a project's plan.org, kept by its agents And over the composer, while it asks or after it pauses with tasks open, one line: "Plan 3 of its tasks open", "Finishing · ask 2" with × to stop asking until the next message, or "Paused · Continue" with why on hover + Rule: PL8. One way to keep work, and any tracker beside it + # Shane, 2026-11-20: "we continually in the desktop app get issues with tasks and starting or adding tasks and it + # never actually closes any out. so maybe we should align plan to be simpler", then "make sure the project management + # structure is clear dry and we dont have competing methods", and "the planning api will need to be able to easily + # sync and extend to whatever system enterprise clients use so we dont want to be too opinionated about planning as + # long as its consistent and fixable by the agent itself too". Read 11-20 in his workspaces: plans kept by an agent in + # a terminal close their tasks (gambit 82 of 133, driveeasier 13 of 13, castle-busters 11 of 13); plans made in the + # app don't (ten new projects hold only the app's own "Write the plan", open; p-pong 0 of 5), with PL7's keeper + # installed. Tasks were written in four places (brief.ts stages, the composer's task per message, the starter task, + # the agents' plan tools) and closed in one: an agent remembering to. Agreed with raea cloud (11-20), whose + # agents keep their projects in plan.org on @raea/task and start them from Asana, Linear, Jira and other boards. + + @done + Scenario: PL8a. plan.org is the one list + # core/brief (brief.rs, parts.rs, tests.rs), apps/workspace doctor.rs, the app's src/brief/spec.ts and format.ts + Then a project's tasks are in its plan.org and nowhere else: brief.ts says what to make (core/brief's Brief has no + stages or tasks), and a brief that still has them reads, its tasks unread, with `raea doctor` saying they + belong in plan.org + And the app's brief writer (src/brief/spec.ts) writes no stages, its starter brief has no ## Tasks, and a brief + that has them moves them into the plan once (PL4c, as before) + And core/brief's object plan, which was also called a plan, is `parts()` in NAME.parts.ts (`raea spec --as parts`) + + @done + Scenario: PL8b. A message is a message, not a task + # the app's src/plan/turn.ts and plan.test.ts; e2e/chat-plan.spec.ts in raea's window + Then the composer writes no task for a message sent: an agent plans tasks when the work is more than its turn + (the skill's plan.md), and the person adds their own in the to-do list + And a new project's plan starts empty, with no "Write the plan" task + + @done + Scenario: PL8c. Closing follows the work + Given a task linked to an item (:ITEM:) + When the person approves that item, or any version of it + Then the task closes DONE, stamped CLOSED, by the person, with no agent asked + And where an open task stands (making, waiting on the person) is read from its item and from a session at work + on it, as the to-do list already shows it (plan/words.ts standing), never from a keyword an agent must remember + to set + And it's checked in the app: src/plan/approve.test.ts, and e2e/todo.spec.ts in raea's window (checking off a + task on an item writes that task DONE) + + @done + Scenario: PL8d. The keywords are the file's + # sdk/task newPlan (test/trackers.test.ts); the app's src/plan/keywords.ts and host/plan.test.ts + Then a plan's #+TODO: lines are its keywords and Org's | says which close a task; raea reads any sequence that way + And a plan the app makes keeps TODO | DONE DROPPED; raea cloud's TODO MAKING REVIEW | DONE DROPPED and a client's + own words read the same, and newPlan(title, keywords) takes the sequence its caller keeps + + @done + Scenario: PL8e. A task kept in step with another tracker + # sdk/task src/trackers.ts; test/trackers.test.ts (with a raea cloud plan.org that passes checkPlan unflagged). + Then a task names its items in other trackers with one property, :LINK: linear:ENG-12 asana:1209876543 (each the + tracker's own key, never a URL; one per system), and the head maps each system's statuses to keywords, one line + a system: #+LINK_STATES: linear In Progress=MAKING; In Review=REVIEW; Done=DONE + And keywordFor(plan, system, status) is a status coming in and statusFor(plan, system, keyword) the status written + back (the first one listed for the keyword), so a sync needs a mapping, not code per client + And trackersOf(task) and trackerStates(plan) read them for a sync or a trigger's match + + @done + Scenario: PL8f. An agent can fix its own plan + Then checkPlan says each problem with its fix: an id on two tasks, a :LINK: entry that isn't SYSTEM:ID or is a + URL, a system named twice on one task, one tracker item on two tasks, a #+LINK_STATES: keyword the plan doesn't + know, and a plugin's kinds and properties (PL6) + And nothing else is required: no :ID:, no keyword on a heading, no property, so headings that group, hold notes or + hold a cloud agent's settings are never flagged diff --git a/sdk/task/src/edit.ts b/sdk/task/src/edit.ts index db0c2b9c..b3ce1688 100644 --- a/sdk/task/src/edit.ts +++ b/sdk/task/src/edit.ts @@ -65,7 +65,9 @@ export const tagOf = (s: string) => s.trim().replace(/^[#:]+/, "").replace(/[^\p export const toggled = (t: { ref: string; state?: State }): PlanEdit => ({ op: "state", ref: t.ref, state: isClosed(t.state) ? "todo" : "done" }) /** A new project's plan: its title, and raea's keywords spelled out for Emacs and any other Org reader. */ -export const newPlan = (title: string) => `#+TITLE: ${title.replace(/\s+/g, " ").trim()}\n#+TODO: TODO MAKING REVIEW | DONE DROPPED\n\n` +/** A new plan.org's text. `keywords` is its #+TODO: sequence: raea's whole one unless the caller keeps fewer (the app + * keeps TODO | DONE DROPPED: where a linked task stands is its item's, PL8). */ +export const newPlan = (title: string, keywords = "TODO MAKING REVIEW | DONE DROPPED") => `#+TITLE: ${title.replace(/\s+/g, " ").trim()}\n#+TODO: ${keywords}\n\n` const oneLine = (s: string) => s.replace(/\s+/g, " ").trim() const propOf = (s: Section, key: string) => s.props?.find(([k]) => k.toUpperCase() === key)?.[1] diff --git a/sdk/task/src/extend.ts b/sdk/task/src/extend.ts index 7368b338..0cd1ad8b 100644 --- a/sdk/task/src/extend.ts +++ b/sdk/task/src/extend.ts @@ -4,6 +4,7 @@ // (TODO MAKING REVIEW | DONE DROPPED), its properties and its views are in every registry from the start. import type { TaskFields } from "./edit.ts" import type { Plan, State, Task } from "./model.ts" +import { trackerProblems } from "./trackers.ts" import { agenda, board, outline } from "./views.ts" export const STATES: readonly State[] = ["todo", "making", "review", "done", "dropped"] @@ -127,7 +128,9 @@ export interface Diagnostic { } /** What is wrong in a plan by the registry's rules: ids used twice, properties that fail their check, kinds nobody - * defined, a kind's missing properties, keywords outside a kind's sequence, and the kinds' own checks. */ + * defined, a kind's missing properties, keywords outside a kind's sequence, the kinds' own checks, and its links to + * other trackers (trackers.ts: an entry that isn't SYSTEM:ID, one tracker item on two tasks, a #+LINK_STATES: + * keyword the plan doesn't know). Nothing else is required: no :ID:, no keyword on a heading, no property. */ export function checkPlan(plan: Plan, reg: PlanRegistry = plans): Diagnostic[] { const out: Diagnostic[] = [] const seen = new Map<string, Task>() @@ -153,5 +156,6 @@ export function checkPlan(plan: Plan, reg: PlanRegistry = plans): Diagnostic[] { const why = kind.check?.(t, plan) if (why) say(why) } + for (const p of trackerProblems(plan)) out.push({ ref: p.task?.ref ?? "head", line: p.task?.line ?? p.line ?? 0, severity: "error", message: p.message }) return out } diff --git a/sdk/task/src/index.ts b/sdk/task/src/index.ts index 2a40d5a3..65f0028c 100644 --- a/sdk/task/src/index.ts +++ b/sdk/task/src/index.ts @@ -9,3 +9,4 @@ export { checkPlan, createRegistry, defineKeywords, definePlanKind, defineProper export { agenda, board, outline, type Agenda, type AgendaDay, type Lane, type OutlineNode } from "./views.ts" export { planDigest, taskLine } from "./digest.ts" export { answerPlanTool, PLAN_TOOLS, planToolEdits, type NewTaskInput, type PlanTool, type PlanToolHost, type TaskChange } from "./tools.ts" +export { keywordFor, statusFor, trackerStates, trackersOf, type Tracker, type TrackerStates } from "./trackers.ts" diff --git a/sdk/task/src/trackers.ts b/sdk/task/src/trackers.ts new file mode 100644 index 00000000..e7c41976 --- /dev/null +++ b/sdk/task/src/trackers.ts @@ -0,0 +1,99 @@ +// A task kept in step with another tracker (Asana, Linear, Jira, ...: raea cloud's board triggers, a client's own +// system), with no code per client: the file says it all (docs/plan.feature PL8). +// :LINK: linear:ENG-12 asana:1209876543 on a task: one SYSTEM:ID per system, the tracker's own key, never a URL +// #+LINK_STATES: linear In Progress=MAKING; In Review=REVIEW; Done=DONE in the head: one line per system +// A status comes in as its keyword (trimmed, any case); a keyword goes out as the FIRST status the line lists for it. +import type { Plan, Task } from "./model.ts" + +export interface Tracker { + system: string + id: string +} + +export interface TrackerStates { + /** a status (lower case, trimmed) to its keyword */ + toKeyword: Map<string, string> + /** a keyword to the first status listed for it, as written */ + toStatus: Map<string, string> +} + +const SYSTEM = /^[a-z0-9][a-z0-9-]*$/ +const STATES_LINE = /^[ \t]*#\+LINK_STATES:[ \t]*(\S+)[ \t]*(.*)$/i + +/** One :LINK: entry, or why it isn't one. */ +function entry(s: string): Tracker | string { + const at = s.indexOf(":") + const system = at > 0 ? s.slice(0, at) : "" + const id = at > 0 ? s.slice(at + 1) : "" + if (!SYSTEM.test(system) || !id) return `"${s}" isn't SYSTEM:ID (linear:ENG-12)` + if (/^\/\/|^https?:/i.test(id) || /^https?$/.test(system)) return `"${s}" is a URL; :LINK: takes the tracker's own key, the URL goes in the task's text` + return { system, id } +} + +/** The trackers a task is kept in step with, in the order its :LINK: names them (what isn't SYSTEM:ID is left out). */ +export function trackersOf(task: Task): Tracker[] { + return (task.props.LINK ?? "").split(/\s+/).filter(Boolean).map(entry).filter((e): e is Tracker => typeof e !== "string") +} + +/** Each system's status map, from the head's #+LINK_STATES: lines. */ +export function trackerStates(plan: Plan): Map<string, TrackerStates> { + const out = new Map<string, TrackerStates>() + for (const line of plan.doc.head) { + const m = STATES_LINE.exec(line) + if (!m) continue + const system = m[1].toLowerCase() + const s = out.get(system) ?? { toKeyword: new Map(), toStatus: new Map() } + for (const pair of m[2].split(";")) { + const eq = pair.lastIndexOf("=") + const status = pair.slice(0, eq).trim() + const keyword = pair.slice(eq + 1).trim() + if (eq < 0 || !status || !keyword) continue + s.toKeyword.set(status.toLowerCase(), keyword) + if (!s.toStatus.has(keyword)) s.toStatus.set(keyword, status) + } + out.set(system, s) + } + return out +} + +/** The keyword a system's status means here, or undefined when the head doesn't map it. */ +export const keywordFor = (plan: Plan, system: string, status: string): string | undefined => + trackerStates(plan).get(system.toLowerCase())?.toKeyword.get(status.trim().toLowerCase()) + +/** The status to write back to a system for a keyword: the first one its line lists, or undefined. */ +export const statusFor = (plan: Plan, system: string, keyword: string): string | undefined => trackerStates(plan).get(system.toLowerCase())?.toStatus.get(keyword) + +/** What's wrong with the plan's links, for checkPlan: an entry that isn't SYSTEM:ID, a system named twice on one task, + * one SYSTEM:ID on two tasks, and a #+LINK_STATES: keyword the plan doesn't know. Each says its fix. */ +export function trackerProblems(plan: Plan): { task?: Task; line?: number; message: string }[] { + const out: { task?: Task; line?: number; message: string }[] = [] + const owner = new Map<string, Task>() + for (const t of plan.entries) { + const systems = new Set<string>() + for (const raw of (t.props.LINK ?? "").split(/\s+/).filter(Boolean)) { + const e = entry(raw) + if (typeof e === "string") { + out.push({ task: t, message: `:LINK: ${e}` }) + continue + } + if (systems.has(e.system)) out.push({ task: t, message: `:LINK: names ${e.system} twice; a task is one item in each system` }) + systems.add(e.system) + const key = `${e.system}:${e.id}` + const was = owner.get(key) + if (was) out.push({ task: t, message: `:LINK: ${key} is also ${was.text}'s; one tracker item is one task, so keep it on one of them`, }) + else owner.set(key, t) + } + } + plan.doc.head.forEach((line, i) => { + const m = STATES_LINE.exec(line) + if (!m) return + if (!SYSTEM.test(m[1].toLowerCase())) out.push({ line: i, message: `#+LINK_STATES: starts with its system's name (linear), not "${m[1]}"` }) + for (const pair of m[2].split(";").map((p) => p.trim()).filter(Boolean)) { + const eq = pair.lastIndexOf("=") + const keyword = eq < 0 ? "" : pair.slice(eq + 1).trim() + if (eq <= 0 || !keyword) out.push({ line: i, message: `#+LINK_STATES: "${pair}" isn't Status=KEYWORD` }) + else if (!plan.words.has(keyword)) out.push({ line: i, message: `#+LINK_STATES: ${keyword} isn't one of this plan's keywords (${[...plan.words.keys()].join(" ")}); add it to #+TODO: or map the status to one that is` }) + } + }) + return out +} diff --git a/sdk/task/test/trackers.test.ts b/sdk/task/test/trackers.test.ts new file mode 100644 index 00000000..c7f23537 --- /dev/null +++ b/sdk/task/test/trackers.test.ts @@ -0,0 +1,149 @@ +// PL8: a task kept in step with another tracker by :LINK: and #+LINK_STATES:, with checkPlan saying what's wrong, and +// a raea cloud plan.org (the cloud's writer, 11-20) passing it with nothing flagged. +import { describe, expect, test } from "vitest" +import { checkPlan, keywordFor, newPlan, readPlan, statusFor, trackersOf, trackerStates } from "../src/index.ts" + +const LINKED = `#+TITLE: Launch +#+TODO: TODO MAKING REVIEW | DONE DROPPED +#+LINK_STATES: linear In Progress=MAKING; In Review=REVIEW; Done=DONE; Canceled=DROPPED; Duplicate=DROPPED + +* Cut +** TODO Hero cut +:PROPERTIES: +:ID: t-hero +:LINK: linear:ENG-12 asana:1209876543 +:END: +` + +describe("PL8: links to other trackers", () => { + test("a task's trackers are its :LINK: entries, in order", () => { + const p = readPlan(LINKED) + expect(trackersOf(p.tasks[0])).toEqual([{ system: "linear", id: "ENG-12" }, { system: "asana", id: "1209876543" }]) + // each tracker's own key, as raea cloud writes them (11-20): GitHub's org/repo#12, Slack's channel/ts, Trello's shortLink + const keys = readPlan(LINKED.replace("linear:ENG-12 asana:1209876543", "github:acme/site#12 slack:C0123/1700000000.123 trello:aB3dE9 jira:PROJ-7")) + expect(trackersOf(keys.tasks[0]).map((t) => t.id)).toEqual(["acme/site#12", "C0123/1700000000.123", "aB3dE9", "PROJ-7"]) + expect(checkPlan(keys)).toEqual([]) + }) + + test("a status comes in as its keyword, and a keyword goes out as the first status listed for it", () => { + const p = readPlan(LINKED) + expect(keywordFor(p, "linear", " in review ")).toBe("REVIEW") + expect(keywordFor(p, "Linear", "Duplicate")).toBe("DROPPED") + expect(statusFor(p, "linear", "DROPPED")).toBe("Canceled") + expect(keywordFor(p, "linear", "Backlog")).toBeUndefined() + expect(keywordFor(p, "jira", "Done")).toBeUndefined() + expect([...trackerStates(p).keys()]).toEqual(["linear"]) + expect(checkPlan(p)).toEqual([]) + }) + + test("checkPlan says what's wrong with a link, and how to fix it", () => { + const bad = `${LINKED.replace("asana:1209876543", "linear:ENG-13 https://linear.app/x ENG-14")}** TODO Same item +:PROPERTIES: +:LINK: linear:ENG-12 +:END: +`.replace("Duplicate=DROPPED", "Blocked=WAITING") + const says = checkPlan(readPlan(bad)).map((d) => d.message) + expect(says.some((m) => /names linear twice/.test(m))).toBe(true) + expect(says.some((m) => /is a URL/.test(m))).toBe(true) + expect(says.some((m) => /"ENG-14" isn't SYSTEM:ID/.test(m))).toBe(true) + expect(says.some((m) => /linear:ENG-12 is also Hero cut's/.test(m))).toBe(true) + expect(says.some((m) => /WAITING isn't one of this plan's keywords/.test(m))).toBe(true) + }) + + test("a new plan keeps the keywords it's given", () => { + expect(newPlan("Pong")).toContain("#+TODO: TODO MAKING REVIEW | DONE DROPPED") + expect(newPlan("Pong", "TODO | DONE DROPPED")).toContain("#+TODO: TODO | DONE DROPPED\n") + }) +}) + +// what raea cloud writes (11-20): an * Agent heading, triggers under * Triggers (and the old * Inputs), +// projects with their properties, a project's own sections, checkpoints, team stage checklists and logbook notes +const CLOUD = `#+TITLE: Cutter +#+TODO: TODO MAKING REVIEW | DONE DROPPED +#+LINK_STATES: linear In Progress=MAKING; In Review=REVIEW; Done=DONE + +* Agent +:PROPERTIES: +:FOR: Acme's paid social +:AT_A_TIME: no limit +:TOOLS: computer judge web +:END: +- [X] Client review (amber): where its review goes +- [ ] Legal (red): legal@acme.com + +* Triggers +** Linear: In Review on ENG +:PROPERTIES: +:TRIGGER: tr-lin1 +:APP: linear +:WHERE: ENG +:SIGNAL: status +:VALUE: In Review +:FIELD: state +:FILTERS: label=video; priority=high +:REPLY: webhook https://hooks.acme.com/raea +:END: +** Every Monday +:PROPERTIES: +:TRIGGER: tr-sched +:AT: 09:00 +:REPEAT: weekly +:END: + +* Inputs +** Old form +:PROPERTIES: +:INPUT: in-1 +:END: + +* Projects +** REVIEW Spring sale cut [1/2] +:PROPERTIES: +:ID: pj-1 +:AGENT: ag-cutter +:BOT: bot-1 +:SKILL: sk-cut +:REPO: project-pj-1 +:ASSIGNEE: email:ana@acme.com Ana Ruiz +:FROM: tr-lin1 +:REPLY: email ana@acme.com +:CLIENT: Acme +:BRAND: Acme +:CREATED: [2026-11-20 Fri 10:02] +:SPENT: 0.039 +:RESPONSES: 3 +:WAITING: Client review +:LINK: linear:ENG-12 +:END: +:LOGBOOK: +- Note taken on [2026-11-20 Fri 10:10] \\\\ + first cut posted +:END: +- [X] Approve the plan +- [ ] Client review: Review the first cut +*** Input +[[https://linear.app/acme/issue/ENG-12][ENG-12]] +*** Attachments +*** Expected output +*** Checkpoint: Approve the plan +:PROPERTIES: +:AT: [2026-11-20 Fri 10:05] +:ANSWER: approve +:NOTE: go +:END: +** DROPPED Old idea +:PROPERTIES: +:ID: pj-0 +:OUTCOME: failed +:END: +*** What went wrong +*** Last answer +*** Delivered +` + +test("PL8: a raea cloud plan.org passes checkPlan with nothing flagged", () => { + const p = readPlan(CLOUD) + expect(checkPlan(p)).toEqual([]) + expect(p.tasks.map((t) => t.keyword)).toEqual(["REVIEW", "DROPPED"]) + expect(trackersOf(p.tasks[0])).toEqual([{ system: "linear", id: "ENG-12" }]) +}) From d90b05017e32933dc24e19b6f8897c96e72cc28f Mon Sep 17 00:00:00 2001 From: shinyobjectz <shinyobjectz@users.noreply.github.com> Date: Fri, 20 Nov 2026 13:09:12 -0800 Subject: [PATCH 2/3] PL8a: a brief has no tasks, and an object's plan is its parts core/brief's Brief drops stages and its Stage, Mark and Task types: a project's tasks are its plan.org. An older brief with stages still reads; raea doctor says its tasks belong in plan.org and moves nothing. core/brief's object plan, the solids contract, is parts() in NAME.parts.ts (raea spec --as parts), so plan means only a project's plan.org. No project used plan(); the bevy guides that teach it, the manual and the reference pages follow. --- apps/workspace/src/doctor.rs | 11 ++++++ apps/workspace/src/tests.rs | 7 ++-- core/brief/src/brief.rs | 51 +++++----------------------- core/brief/src/lib.rs | 10 +++--- core/brief/src/{plan.rs => parts.rs} | 13 +++---- core/brief/src/tests.rs | 26 ++++++++------ docs/manual/concepts/workspaces.md | 2 +- docs/manual/reference/cli/index.md | 2 +- docs/manual/reference/cli/spec.md | 8 ++--- docs/manual/reference/sdk/brief.md | 37 ++++++-------------- docs/manual/reference/sdk/index.md | 2 +- engine/cli/src/cli.rs | 2 +- engine/cli/src/spec.rs | 12 +++---- sdk/guides/craft/bevy/prompts.md | 12 +++---- sdk/guides/craft/bevy/scenes.md | 4 +-- sdk/raea/src/brief.gen.ts | 22 ++---------- sdk/raea/src/brief.ts | 9 ++--- tools/skills.sh | 2 +- 18 files changed, 92 insertions(+), 140 deletions(-) rename core/brief/src/{plan.rs => parts.rs} (88%) diff --git a/apps/workspace/src/doctor.rs b/apps/workspace/src/doctor.rs index 952af1cc..9037419c 100644 --- a/apps/workspace/src/doctor.rs +++ b/apps/workspace/src/doctor.rs @@ -86,6 +86,16 @@ fn old_controllers(base: &Path, ws: Option<&Path>, out: &mut Vec<Finding>) { } } +/// A brief.ts that still keeps tasks in `stages` (docs/plan.feature PL8a): they read, unread, and belong in plan.org. +fn briefs_with_tasks(base: &Path, out: &mut Vec<Finding>) { + let f = base.join("brief.ts"); + let Ok(text) = std::fs::read_to_string(&f) else { return }; + if text.lines().any(|l| l.trim_start().starts_with("stages:") || l.trim_start().starts_with("\"stages\":")) { + let says = format!("{}: keeps tasks in `stages`, which raea no longer reads; move each to the project's plan.org (an Org heading under its stage, its mark as TODO, DONE or DROPPED), then delete `stages`", f.display()); + out.push(Finding { says, fix: Fix::No }); + } +} + /// The `version:` in a SKILL.md's front matter. fn skill_version(md: &Path) -> Option<String> { let text = std::fs::read_to_string(md).ok()?; @@ -101,6 +111,7 @@ pub fn findings(from: &Path, skills: &[(&str, PathBuf)], version: &str) -> Vec<F let base = project.clone().or_else(|| ws.clone()).unwrap_or_else(|| from.to_path_buf()); old_briefs(&base, if project.is_some() { 2 } else { 1 }, &mut out); old_controllers(&base, ws.as_deref(), &mut out); + briefs_with_tasks(&base, &mut out); if let Some(ws) = &ws { let name = ws.file_name().map(|n| n.to_string_lossy().into_owned()).unwrap_or_default(); let keys = [("workspace.id", new_id("ws")), ("workspace.name", name), ("workspace.layout", "monorepo".to_string())]; diff --git a/apps/workspace/src/tests.rs b/apps/workspace/src/tests.rs index bb70cf7c..c99a046b 100644 --- a/apps/workspace/src/tests.rs +++ b/apps/workspace/src/tests.rs @@ -83,14 +83,17 @@ fn doctor_connects_a_projects_files() { std::fs::write(d.join("loose.tsx"), "export const Loose = () => null;\n").unwrap(); std::fs::create_dir_all(d.join("controllers")).unwrap(); std::fs::write(d.join("controllers/pace.ts"), "import { controller } from \"raea/brief\";\nexport default controller({ title: \"Pace\", fields: {} });\n").unwrap(); + std::fs::write(d.join("brief.ts"), "import { brief } from \"raea/brief\";\nexport default brief({\n title: \"Old\",\n stages: [{ name: \"\", tasks: [{ text: \"Write the plan\" }] }],\n});\n").unwrap(); let found = doctor::registry_findings(&d); let says: Vec<&String> = found.iter().map(|f| &f.says).collect(); assert_eq!(found.len(), 1, "{says:?}"); assert!(says[0].contains("loose.tsx:1: isn't a composition") && !found[0].fixable(), "{says:?}"); // a controller from before 11-20 is told where its parts go, and kept let out = doctor::doctor(&["--fix".into(), d.display().to_string()], &[], "0.0.1", &|_| Ok(String::new())).unwrap(); - assert!(out.starts_with("APPLIED 2 of 4 fixed") && out.contains("controllers/pace.ts: a controller, which raea no longer reads") && out.contains("taste.ts"), "{out}"); - assert!(d.join("controllers/pace.ts").is_file(), "nothing of the person's is deleted"); + assert!(out.starts_with("APPLIED 2 of 5 fixed") && out.contains("controllers/pace.ts: a controller, which raea no longer reads") && out.contains("taste.ts"), "{out}"); + // a brief's old tasks are said to belong in plan.org (docs/plan.feature PL8a), and kept + assert!(out.contains("brief.ts: keeps tasks in `stages`") && out.contains("plan.org"), "{out}"); + assert!(d.join("controllers/pace.ts").is_file() && std::fs::read_to_string(d.join("brief.ts")).unwrap().contains("stages"), "nothing of the person's is deleted"); let _ = std::fs::remove_dir_all(&d); } diff --git a/core/brief/src/brief.rs b/core/brief/src/brief.rs index 9e4c3a48..840eaf41 100644 --- a/core/brief/src/brief.rs +++ b/core/brief/src/brief.rs @@ -1,5 +1,6 @@ -//! A project's brief: who it's for, the one thing they should believe, what it delivers and the work to get there. -//! The facts an agent guessed are listed in `assumed`, for the person to confirm. +//! A project's brief: who it's for, the one thing they should believe and what it delivers. The facts an agent guessed +//! are listed in `assumed`, for the person to confirm. Its tasks are in the project's plan.org, not here +//! (docs/plan.feature PL8a). use serde::{Deserialize, Serialize}; use ts_rs::TS; @@ -47,10 +48,11 @@ pub struct Brief { #[serde(default)] #[ts(as = "Option<Vec<Reference>>", optional)] pub references: Vec<Reference>, - /// the tasks, in stages ("Act one", "The cut") - #[serde(default)] - #[ts(as = "Option<Vec<Stage>>", optional)] - pub stages: Vec<Stage>, + /// an older brief's tasks, read only so it still loads: they belong in plan.org (docs/plan.feature PL8a), and + /// `raea doctor` says so; never written, and not in the schema an agent writes to + #[serde(default, skip_serializing)] + #[ts(skip)] + pub stages: Option<serde_json::Value>, #[serde(default)] #[ts(as = "Option<Vec<Agent>>", optional)] pub agents: Vec<Agent>, @@ -88,43 +90,6 @@ pub struct Reference { pub note: Option<String>, } -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, TS)] -#[serde(deny_unknown_fields)] -pub struct Stage { - pub name: String, - pub tasks: Vec<Task>, -} - -#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, TS)] -#[serde(rename_all = "lowercase")] -pub enum Mark { - #[default] - Todo, - Done, - Dropped, -} - -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, TS)] -#[serde(rename_all = "camelCase", deny_unknown_fields)] -#[ts(optional_fields)] -pub struct Task { - pub text: String, - /// a task linked to an item takes the item's state (the work is the truth); this is for unlinked ones - #[serde(default)] - #[ts(as = "Option<Mark>", optional)] - pub mark: Mark, - #[serde(default)] - #[ts(as = "Option<Vec<String>>", optional)] - pub agents: Vec<String>, - pub item: Option<String>, - #[serde(default)] - #[ts(as = "Option<Vec<String>>", optional)] - pub tags: Vec<String>, - pub due: Option<String>, - /// the craft verb it was written as ("quieter"): agents read it, the page shows the text - pub verb: Option<String>, -} - #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, TS)] #[serde(deny_unknown_fields)] #[ts(optional_fields)] diff --git a/core/brief/src/lib.rs b/core/brief/src/lib.rs index 1af26aa8..af30957d 100644 --- a/core/brief/src/lib.rs +++ b/core/brief/src/lib.rs @@ -1,15 +1,15 @@ //! What an agent writes for raea, as Rust types: a project's brief, a script (storyboard or screenplay), a person's -//! taste and an object's plan. The agent writes them as TypeScript modules (docs/handoff/authoring.md); `raea run` +//! taste and an object's parts. The agent writes them as TypeScript modules (docs/handoff/authoring.md); `raea run` //! evaluates one, and its default export arrives here as JSON. The TypeScript declarations are generated from these //! types (`declarations`), so what tsc checks is exactly what this crate reads. pub mod brief; -pub mod plan; +pub mod parts; pub mod script; pub mod taste; pub use brief::Brief; -pub use plan::Plan; +pub use parts::Parts; pub use script::Script; pub use taste::Taste; @@ -32,10 +32,10 @@ pub fn declarations() -> String { let cfg = Config::new(); let mut out = vec!["// Generated from raea-core-brief (core/brief) by its `declarations`; edit the Rust, not this.".to_string()]; out.extend(decls!(cfg; - brief::Brief, brief::Section, brief::Deliverable, brief::Reference, brief::Stage, brief::Mark, brief::Task, brief::Agent, + brief::Brief, brief::Section, brief::Deliverable, brief::Reference, brief::Agent, script::Script, script::Scene, script::Beat, script::Line, taste::Taste, taste::TasteSection, taste::Rule, taste::RuleCheck, taste::RuleLevel, taste::Check, - plan::Plan, plan::Concept, plan::Level, plan::Count, plan::Part, + parts::Parts, parts::Concept, parts::Level, parts::Count, parts::Part, )); out.join("\n\n") + "\n" } diff --git a/core/brief/src/plan.rs b/core/brief/src/parts.rs similarity index 88% rename from core/brief/src/plan.rs rename to core/brief/src/parts.rs index ce0e288b..eaad09a7 100644 --- a/core/brief/src/plan.rs +++ b/core/brief/src/parts.rs @@ -1,5 +1,6 @@ -//! An object's plan, written before any geometry and frozen when building starts (docs/handoff/solids.md, "The plan -//! is the contract"). Generic over what's made: a crown, a feather and a rocking horse are all a concept and a tree of +//! An object's parts (NAME.parts.ts, `parts()` from "raea/brief"), written before any geometry and frozen when +//! building starts (docs/handoff/solids.md, "The plan is the contract"; named parts since 11-20, so "plan" is only a +//! project's plan.org, docs/plan.feature PL8a). Generic over what's made: a crown, a feather and a rocking horse are all a concept and a tree of //! named parts, each with a level, a count, and a material and style it has or inherits. use std::collections::BTreeMap; @@ -9,7 +10,7 @@ use ts_rs::TS; #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, TS)] #[serde(deny_unknown_fields)] -pub struct Plan { +pub struct Parts { pub concept: Concept, /// by name; the build's parts are typed from these keys, so a planned part the build skips is a tsc error pub parts: BTreeMap<String, Part>, @@ -77,7 +78,7 @@ pub struct Resolved { /// Everything wrong with a plan that would let a build leave something behind: a parent that isn't planned, a loop, /// no root, a range upside down, or a part that resolves to no material. Empty when the plan can be built against. -pub fn check(plan: &Plan) -> Vec<String> { +pub fn check(plan: &Parts) -> Vec<String> { let mut out = Vec::new(); let roots: Vec<&String> = plan.parts.iter().filter(|(_, p)| p.parent.is_none()).map(|(n, _)| n).collect(); if roots.is_empty() { @@ -107,7 +108,7 @@ pub fn check(plan: &Plan) -> Vec<String> { } /// The part and its ancestors, nearest first; none on a loop or a missing parent. -fn chain<'a>(plan: &'a Plan, name: &str) -> Option<Vec<&'a Part>> { +fn chain<'a>(plan: &'a Parts, name: &str) -> Option<Vec<&'a Part>> { let mut out = Vec::new(); let mut at = plan.parts.get(name)?; loop { @@ -124,7 +125,7 @@ fn chain<'a>(plan: &'a Plan, name: &str) -> Option<Vec<&'a Part>> { /// A part's material and style, inherited up its parents to the concept. Style always resolves (the concept has /// one); material may not. -pub fn resolve(plan: &Plan, name: &str) -> Option<Resolved> { +pub fn resolve(plan: &Parts, name: &str) -> Option<Resolved> { let chain = chain(plan, name)?; let material = chain.iter().find_map(|p| p.material.clone()).or_else(|| plan.concept.material.clone())?; let style = chain.iter().find_map(|p| p.style.clone()).unwrap_or_else(|| plan.concept.style.clone()); diff --git a/core/brief/src/tests.rs b/core/brief/src/tests.rs index ce6e06e6..14d289a6 100644 --- a/core/brief/src/tests.rs +++ b/core/brief/src/tests.rs @@ -14,9 +14,7 @@ fn declarations_match_the_committed_file() { #[test] fn a_brief_reads_and_its_doctor_asks_for_what_is_missing() { let b: Brief = read("brief.ts", r#"{"title": "A walkthrough", "mode": ["explain"], "assumed": ["voice"], "voice": "one calm narrator", - "deliver": [{"name": "Walkthrough", "specs": ["60 s", "16:9"]}], - "stages": [{"name": "", "tasks": [{"text": "Storyboard it", "agents": ["director"], "mark": "done"}]}]}"#).unwrap(); - assert_eq!(b.stages[0].tasks[0].mark, brief::Mark::Done); + "deliver": [{"name": "Walkthrough", "specs": ["60 s", "16:9"]}]}"#).unwrap(); let d = brief::doctor(&b); assert!(d.iter().any(|m| m.contains("`believe`")), "{d:?}"); assert!(d.iter().any(|m| m.contains("no script")), "{d:?}"); @@ -68,26 +66,34 @@ fn a_taste_line_holds_any_check_by_name_or_path_with_values_and_a_level() { } #[test] -fn a_plan_leaves_nothing_without_a_material() { - let ok: Plan = read("plan.ts", r#"{"concept": {"what": "flight feather", "style": "realistic", "size": 0.25, "seenFrom": 0.3, "material": "keratin"}, +fn an_objects_parts_leave_nothing_without_a_material() { + let ok: Parts = read("feather.parts.ts", r#"{"concept": {"what": "flight feather", "style": "realistic", "size": 0.25, "seenFrom": 0.3, "material": "keratin"}, "parts": { "rachis": {"role": "shaft", "level": "primary"}, "vane": {"role": "vane", "level": "secondary", "parent": "rachis", "count": 2, "style": "barred brown"}, "barb": {"role": "barb", "level": "tertiary", "parent": "vane", "count": {"min": 300, "max": 500}, "near": "separate barbs, a few split gaps"}}}"#).unwrap(); - assert_eq!(plan::check(&ok), Vec::<String>::new()); - assert_eq!(plan::resolve(&ok, "barb").unwrap(), plan::Resolved { material: "keratin".into(), style: "barred brown".into() }); + assert_eq!(parts::check(&ok), Vec::<String>::new()); + assert_eq!(parts::resolve(&ok, "barb").unwrap(), parts::Resolved { material: "keratin".into(), style: "barred brown".into() }); let mut bad = ok.clone(); bad.concept.material = None; bad.parts.get_mut("rachis").unwrap().parent = Some("calamus".into()); - let e = plan::check(&bad); + let e = parts::check(&bad); assert!(e.iter().any(|m| m.contains("`calamus` isn't planned")), "{e:?}"); assert!(e.iter().any(|m| m.contains("no root")), "{e:?}"); } #[test] fn a_close_view_needs_tertiary_detail() { - let p: Plan = read("plan.ts", r#"{"concept": {"what": "toy rocking horse", "style": "painted wood", "size": 0.9, "seenFrom": 0.5, "material": "beech"}, + let p: Parts = read("horse.parts.ts", r#"{"concept": {"what": "toy rocking horse", "style": "painted wood", "size": 0.9, "seenFrom": 0.5, "material": "beech"}, "parts": {"body": {"role": "body", "level": "primary"}, "rocker": {"role": "rocker", "level": "secondary", "parent": "body", "count": 2}}}"#).unwrap(); - assert!(plan::check(&p).iter().any(|m| m.contains("tertiary"))); + assert!(parts::check(&p).iter().any(|m| m.contains("tertiary"))); +} + +#[test] +fn an_older_brief_with_stages_still_reads_and_never_writes_them() { + let b: Brief = read("brief.ts", r#"{"title": "Old", "stages": [{"name": "", "tasks": [{"text": "Write the plan", "mark": "todo"}]}]}"#).unwrap(); + assert!(b.stages.is_some()); + assert!(!serde_json::to_string(&b).unwrap().contains("stages")); + assert!(!declarations().contains("stages"), "the schema an agent writes has no stages (docs/plan.feature PL8a)"); } diff --git a/docs/manual/concepts/workspaces.md b/docs/manual/concepts/workspaces.md index 5b09a594..5f900b60 100644 --- a/docs/manual/concepts/workspaces.md +++ b/docs/manual/concepts/workspaces.md @@ -56,7 +56,7 @@ raea's specs are TypeScript files whose default export is checked against a sche | `NAME.script.ts` | A storyboard: scenes of beats, what's on screen, what each scene must land | | `~/.raea/taste/taste.ts` | The person's taste, which beats any guide's default | | `taste.ts` | A workspace's or a project's rules, which `raea check` holds every piece to | -| `plan.ts` | A frozen plan for a build, checked by raea | +| `NAME.parts.ts` | An object's parts, frozen before it's built, checked by raea | ```sh raea spec brief.ts # prints the brief as JSON, checked against its schema diff --git a/docs/manual/reference/cli/index.md b/docs/manual/reference/cli/index.md index 648ffdcf..8d361139 100644 --- a/docs/manual/reference/cli/index.md +++ b/docs/manual/reference/cli/index.md @@ -49,7 +49,7 @@ The workspace, its projects and what a project holds. | [`raea init`](init.md) | Add a project's starting files where they're missing: edit.tsx, cuts.ts, components/ and AGENTS.md. | | [`raea workspace`](workspace.md) | Make, adopt or show a workspace: the git repository that holds a studio's projects and house taste. | | [`raea project`](project.md) | Make a project in the workspace, list them, or move one between inline and a repository of its own. | -| [`raea spec`](spec.md) | Print a spec file's default export as JSON, checked against its schema: briefs, scripts, taste and plans. | +| [`raea spec`](spec.md) | Print a spec file's default export as JSON, checked against its schema: briefs, scripts, taste and an object's parts. | | [`raea component`](component.md) | Copy a ready-made component or set into the project's components/, or the workspace's shared/components/, to use and change as your own. | | [`raea part`](part.md) | The old name of raea component: copy a ready-made component into the project's components/, to use and change as your own. | | [`raea add`](add.md) | Add, remove and install npm packages for a project, with no Node or npm: raea.lock and node_modules. | diff --git a/docs/manual/reference/cli/spec.md b/docs/manual/reference/cli/spec.md index eeb1f251..664ecc4b 100644 --- a/docs/manual/reference/cli/spec.md +++ b/docs/manual/reference/cli/spec.md @@ -1,12 +1,12 @@ --- title: "raea spec" -summary: "Print a spec file's default export as JSON, checked against its schema: briefs, scripts, taste and plans." +summary: "Print a spec file's default export as JSON, checked against its schema: briefs, scripts, taste and an object's parts." order: 25 sources: ["engine/cli/src/spec.rs"] --- raea's specs are TypeScript files whose default export is data: `brief.ts`, `NAME.script.ts`, `taste.ts` and -`plan.ts`. `raea spec` evaluates one, checks it against its schema and prints it as JSON, +`NAME.parts.ts`. `raea spec` evaluates one, checks it against its schema and prints it as JSON, so an agent can read a brief without running anything else, and a wrong field is caught before it matters. ```sh @@ -20,7 +20,7 @@ raea spec notes.ts --as taste ## Usage ```sh -raea spec FILE.ts [--as brief|script|taste|plan] (a spec's default export as JSON, checked against its schema: brief.ts, script.ts, taste.ts, plan.ts) +raea spec FILE.ts [--as brief|script|taste|parts] (a spec's default export as JSON, checked against its schema: brief.ts, script.ts, taste.ts, NAME.parts.ts) ``` Headless: it needs nothing running and opens no window. Takes up to 1 argument besides its flags. @@ -29,6 +29,6 @@ Headless: it needs nothing running and opens no window. Takes up to 1 argument b | Flag | Takes | What it does | | --- | --- | --- | -| `--as` | `brief\|script\|taste\|plan` | Which schema to check it against. By default from the file's name (`brief`, `script`, `plan`), and `taste` otherwise. | +| `--as` | `brief\|script\|taste\|parts` | Which schema to check it against. By default from the file's name (`brief`, `script`, `parts`), and `taste` otherwise. | <!-- generated:end --> diff --git a/docs/manual/reference/sdk/brief.md b/docs/manual/reference/sdk/brief.md index 954d75f9..9314ab1a 100644 --- a/docs/manual/reference/sdk/brief.md +++ b/docs/manual/reference/sdk/brief.md @@ -1,6 +1,6 @@ --- title: "raea/brief" -summary: "The specs an agent writes as data: brief, script, taste and plan, checked against raea's schemas." +summary: "The specs an agent writes as data: brief, script, taste and an object's parts, checked against raea's schemas." order: 4 sources: ["sdk/raea/src/brief.ts", "core/brief/src"] --- @@ -30,16 +30,17 @@ See [Workspaces and projects](../../concepts/workspaces.md) for where each spec <!-- generated:begin by tools/manual-ref/sdk.ts from the SDK's exports and doc comments; edit outside this block --> ```ts -import { brief, fingerprint, plan, script } from "raea/brief" +import { brief, fingerprint, parts, script } from "raea/brief" ``` -`raea/brief` exports 5 functions, 27 types. Source: [sdk/raea/src/brief.ts](https://github.com/shinyobjectz/raea/blob/main/sdk/raea/src/brief.ts). +`raea/brief` exports 5 functions, 24 types. Source: [sdk/raea/src/brief.ts](https://github.com/shinyobjectz/raea/blob/main/sdk/raea/src/brief.ts). ## Functions ### `brief` -A project's brief (brief.ts): what to make, for whom, the one thing to believe, its deliverables and staged tasks. +A project's brief (brief.ts): what to make, for whom, the one thing to believe and its deliverables. Its tasks are +the project's plan.org. ```ts function brief(b: Brief): Brief @@ -53,12 +54,12 @@ A fingerprint (fingerprint.ts): its axes and the encoders its heads were trained function fingerprint(f: Fingerprint): Fingerprint ``` -### `plan` +### `parts` -An object's plan (plan.ts): its parts by name, levels, counts, materials. +An object's parts (NAME.parts.ts), written before any geometry: each by name, its level, count and material. ```ts -function plan(p: Plan): Plan +function parts(p: Parts): Parts ``` ### `script` @@ -170,12 +171,6 @@ type Level = "primary" | "secondary" | "tertiary" type Line = { /** * a character, or "narrator" */ who: string, says: string, /** * a screenplay's parenthetical ("quietly") */ how?: string, } ``` -### `Mark` - -```ts -type Mark = "todo" | "done" | "dropped" -``` - ### `Modality` What an axis's head reads: the frames (SigLIP 2), how they change, their look, the sound (CLAP) or its events (YAMNet). @@ -190,10 +185,10 @@ type Modality = "picture" | "change" | "look" | "sound" | "events" | "text" type Part = { /** * the label it carries into the world ("seat", "leaf", "gem") */ role: string, level: Level, /** * the part it sits on or in; none for the root */ parent?: string, count?: Count, /** * its own, else its parent's, else the concept's */ material?: string, style?: string, /** * what a near cro… ``` -### `Plan` +### `Parts` ```ts -type Plan = { concept: Concept, /** * by name; the build's parts are typed from these keys, so a planned part the build skips is a tsc error */ parts: { [key in string]: Part }, } +type Parts = { concept: Concept, /** * by name; the build's parts are typed from these keys, so a planned part the build skips is a tsc error */ parts: { [key in string]: Part }, } ``` ### `Reference` @@ -238,18 +233,6 @@ type Script = { title: string, logline?: string, scenes: Array<Scene>, } type Section = { heading: string, text: string, } ``` -### `Stage` - -```ts -type Stage = { name: string, tasks: Array<Task>, } -``` - -### `Task` - -```ts -type Task = { text: string, /** * a task linked to an item takes the item's state (the work is the truth); this is for unlinked ones */ mark?: Mark, agents?: Array<string>, item?: string, tags?: Array<string>, due?: string, /** * the craft verb it was written as ("quieter"): agents read it, the page shows th… -``` - ### `Taste` ```ts diff --git a/docs/manual/reference/sdk/index.md b/docs/manual/reference/sdk/index.md index 71488223..1ad8240d 100644 --- a/docs/manual/reference/sdk/index.md +++ b/docs/manual/reference/sdk/index.md @@ -33,7 +33,7 @@ The composition, the app, and the specs and notes an agent writes. | --- | --- | --- | | [`raea`](raea.md) | The main entry: compositions, sequences, time, interpolation, springs, footage, sound and words. | 20 components, 9 hooks, 62 functions, 11 values, 107 types | | [`raea/app`](app.md) | The App, its plugins and schedules, and the registry a video's compositions are kept in. | 1 component, 1 hook, 4 functions, 3 classes, 17 values, 17 types | -| [`raea/brief`](brief.md) | The specs an agent writes as data: brief, script, taste and plan, checked against raea's schemas. | 5 functions, 27 types | +| [`raea/brief`](brief.md) | The specs an agent writes as data: brief, script, taste and an object's parts, checked against raea's schemas. | 5 functions, 24 types | | [`raea/note`](note.md) | A person's note as a file in the project: their words kept as written, and the asks the agent restates it as. | 1 function, 4 types | ## Time and motion diff --git a/engine/cli/src/cli.rs b/engine/cli/src/cli.rs index 52c1bb18..69c72658 100644 --- a/engine/cli/src/cli.rs +++ b/engine/cli/src/cli.rs @@ -143,7 +143,7 @@ pub fn run(args: &[String]) -> R<String> { // an agent's report of a bug in raea itself, to raea's server (engine/cli/src/bug.ts; Shane 11-16) let usage = format!("{usage}\n raea bug TITLE... --text TEXT [--command CMD] [--error TEXT] [--agent NAME] [--dry-run] (a bug in raea itself, not in your own composition, sent to raea's server with raea's version and the OS, no account needed: words only, paths, emails and keys taken out before it goes; five a day from a machine, the same bug again counted on the first report; --dry-run prints what would go and sends nothing)"); // a workspace's files and specs (docs/projects.feature), listed under render's usage like library - let usage = format!("{usage}\n raea spec FILE.ts [--as brief|script|taste|plan] (a spec's default export as JSON, checked against its schema: brief.ts, script.ts, taste.ts, plan.ts)\n raea workspace init [NAME] [--layout LAYOUT] | raea workspace adopt DIR [--name NAME] | raea workspace [--json] (a workspace: a git repo of projects under raea.root, ~/Documents/raea unless git config says)\n raea project new NAME [--storage inline|submodule] | raea project split NAME [--remote URL] | raea project join NAME | raea project [--json] (a project in the workspace: its folder, brief.ts, media/, out/; split and join keep its history)\n raea check EDIT.tsx --quick [--shape S] [--platform P] [--taste T] [-o check.json] (three stills of a composition checked for text: clipped, cramped, safe areas, sizes; about a second)\n raea hook [claude|codex|gemini|kimi] (every agent's tool hooks, which raea skills install adds: before a shell command, media opened in the Mac's viewer while the raea app is installed is stopped once for raea show (the same command again goes through); after a save, the quick check on a composition)\n raea next [DIR] (the two or three useful next steps for the project, from its brief, compositions, renders and checks)\n raea doctor [--fix] [DIR] (what doesn't match this raea: old brief files, an older workspace format, an agent's skill from another version)\n raea app run|check|bundle APP.tsx [--target web|native] [--size WxH] [--script steps.json] [--png DIR] [-o App.app] (a TSX app on @raea/ui: its window, the headless check, a Mac app; web is Blitz on Bevy, native is Rune; the app's `export const app` sets the target, web when it doesn't; raea rune ... is --target native)\n {}\n {}\n {} ({})\n {}\n {}\n {}", skill::USAGE, tools::blender::USAGE, tools::motion::SETUP_USAGE, tools::motion::SETUP_ABOUT, raea_app_engines::godot::USAGE, raea_app_engines::shot::USAGE, raea_app_engines::round::USAGE); + let usage = format!("{usage}\n raea spec FILE.ts [--as brief|script|taste|parts] (a spec's default export as JSON, checked against its schema: brief.ts, script.ts, taste.ts, NAME.parts.ts)\n raea workspace init [NAME] [--layout LAYOUT] | raea workspace adopt DIR [--name NAME] | raea workspace [--json] (a workspace: a git repo of projects under raea.root, ~/Documents/raea unless git config says)\n raea project new NAME [--storage inline|submodule] | raea project split NAME [--remote URL] | raea project join NAME | raea project [--json] (a project in the workspace: its folder, brief.ts, media/, out/; split and join keep its history)\n raea check EDIT.tsx --quick [--shape S] [--platform P] [--taste T] [-o check.json] (three stills of a composition checked for text: clipped, cramped, safe areas, sizes; about a second)\n raea hook [claude|codex|gemini|kimi] (every agent's tool hooks, which raea skills install adds: before a shell command, media opened in the Mac's viewer while the raea app is installed is stopped once for raea show (the same command again goes through); after a save, the quick check on a composition)\n raea next [DIR] (the two or three useful next steps for the project, from its brief, compositions, renders and checks)\n raea doctor [--fix] [DIR] (what doesn't match this raea: old brief files, an older workspace format, an agent's skill from another version)\n raea app run|check|bundle APP.tsx [--target web|native] [--size WxH] [--script steps.json] [--png DIR] [-o App.app] (a TSX app on @raea/ui: its window, the headless check, a Mac app; web is Blitz on Bevy, native is Rune; the app's `export const app` sets the target, web when it doesn't; raea rune ... is --target native)\n {}\n {}\n {} ({})\n {}\n {}\n {}", skill::USAGE, tools::blender::USAGE, tools::motion::SETUP_USAGE, tools::motion::SETUP_ABOUT, raea_app_engines::godot::USAGE, raea_app_engines::shot::USAGE, raea_app_engines::round::USAGE); let (export_game, capcut, layers, xml, scene, physics, splat, wear) = (raea_app_game::USAGE, raea_app_capcut::USAGE, raea_app_layers::USAGE, raea_app_layers::USAGE_XML, export::SCENE_USAGE, motion::physics::USAGE, tools::splat::USAGE, raea_runtime_wear::USAGE); let apps = format!(" {}\n {}\n {}\n {}\n {}\n {}\n {}\n {}\n {}\n", raea_app_direction::check::USAGE, raea_app_check::USAGE, raea_app_solid::USAGE, raea_app_judge::USAGE, raea_app_direction::USAGE, raea_app_direction::findings::USAGE, raea_app_notes::USAGE, raea_app_fingerprint::USAGE, raea_sys_index::cli::USAGE); return Ok(format!("raea: renders, plays and checks raea compositions (React and TypeScript) on the GPU.\n\nusage: {usage}\n raea init (a project's files where they're missing: edit.tsx, cuts.ts, components/, AGENTS.md)\n raea cut TAKE \"line\" ... | --at A-B ... [--append] (cuts.ts and words.json: a take under media/ cut in the pauses around each line it says, transcribed first if it has no TAKE.words.json; or at those seconds)\n raea frame TAKE [--at S] (how a take fits the edit: a talking take for <FaceFrame>, a screen for <ScreenFit>, from where its face is)\n raea component list | raea component add NAME ... [--shared] [--force] | raea part list | raea part add NAME ... [--shared] [--force] (a ready component or set copied into components/, or the workspace's shared/components/ with --shared, yours to change; raea part is its old name)\n raea brand DOMAIN|URL (the brand kit read from its website on this machine: brand/brand.css, brand/brand.json, BRAND.md, logos in media/brand; says when a plain fetch saw too little)\n raea guide [NAME] (craft, the floor read before any edit; the modes: pitch, explain, story, play, tool; motion, music, layout and the rest; bevy and bevy/NAME for 3D)\n raea context PROJECT (what to read before working on a project: taste, brief, look, the floor and its modes' guides)\n{apps} raea play EDIT.tsx [--input | --input-script KEYS.json] [--size WxH] [--seconds N|end] (a game, live; also: --input-log FILE --offscreen --snapshot T FILE --json FILE --seek F FILE --pick X,Y --view YAW,PITCH,DISTANCE --scrub N --baked --autoplay --no-vsync --master --3d)\n {export_game} (a game as a program of its own: a Mac app or a command)\n {capcut}\n {layers}\n {xml}\n {scene} (what each 3D part rests on: floating, sunk and clipping parts; light: the scene's lighting)\n {physics} (the bakes <Physics> and <Goo> make)\n {wear} (a .glb's weathering causes for raea/wear: the model with a second UV set and its cause maps, made once in the asset store)\n {splat} (footage trained into a Gaussian splat for <Splat>; setup installs its tools)\n raea run SCRIPT.ts (a TypeScript program on the engine, headless: its default export is called, what it prints is the answer; a check like a room's checkLayout; also: --timeout S)\n raea gen image|video|music|sfx|speech|mesh|text \"PROMPT\" | gen plan|run FLOW.ts|FLOW.json | gen comfy import|export|run|schema FILE | gen models | gen balance (generated media through made.app, fal, Replicate, OpenRouter, Modal or ComfyUI; ComfyUI workflows both ways: raea gen alone lists its flags)\n {neural_usage} (DLSS 5 neural rendering on a `render --aov` folder, with its motion and depth: your own MLX-DLSS build and weights, RAEA_MLXDLSS and RAEA_DLSS_MODEL)\n {light_usage} (each scene on each light path against its path-traced reference: distance in stops, the worst tile, a moving shot's flicker, a frame's cost; DIR/report.json)\n raea mezz [--check] PATH... (an intra-only ProRes copy of each long-GOP source over 1080p, for smooth scrubbing; --check says which would get one)\n raea traces [show [N|last|DIR]] (the sessions raea left, newest first: how each ended, its glitches; show tells one in full)")); diff --git a/engine/cli/src/spec.rs b/engine/cli/src/spec.rs index 40255d73..a5149046 100644 --- a/engine/cli/src/spec.rs +++ b/engine/cli/src/spec.rs @@ -1,5 +1,5 @@ //! Specs written in TypeScript (docs/handoff/authoring.md, docs/projects.feature PJ0): brief.ts, script.ts, taste.ts -//! and plan.ts. A spec is a module whose default export is data; the engine evaluates it headless +//! and NAME.parts.ts (an object's parts). A spec is a module whose default export is data; the engine evaluates it headless //! (bundle_module with PRINT_DEFAULT, run_bundle) and Rust reads the JSON against the schema in core/brief, so tsc's errors come first and //! these come second, naming the field. use super::*; @@ -89,14 +89,14 @@ pub fn tastes_ts(args: &[String]) -> R<Vec<schema::Taste>> { } /// `raea spec FILE.ts [--as KIND]`: the default export as JSON, checked as KIND (by default from the file's name: -/// brief, script, taste or plan in it; anything else is checked as Taste, the files in +/// brief, script, taste or parts in it; anything else is checked as Taste, the files in /// ~/.raea/taste being named for their kind). pub fn spec_cli(args: &[String]) -> R<String> { - const USAGE: &str = "usage: raea spec FILE.ts [--as brief|script|taste|plan]"; + const USAGE: &str = "usage: raea spec FILE.ts [--as brief|script|taste|parts]"; let file = args.iter().enumerate().find(|(i, a)| !a.starts_with("--") && (*i == 0 || args[i - 1] != "--as")).map(|(_, a)| PathBuf::from(a)).ok_or(USAGE)?; let kind = args.iter().position(|a| a == "--as").and_then(|i| args.get(i + 1)).cloned().unwrap_or_else(|| { let base = file.file_name().map(|n| n.to_string_lossy().to_lowercase()).unwrap_or_default(); - ["brief", "script", "plan"].iter().find(|k| base.contains(*k)).map(|k| k.to_string()).unwrap_or_else(|| "taste".into()) + ["brief", "script", "parts"].iter().find(|k| base.contains(*k)).map(|k| k.to_string()).unwrap_or_else(|| "taste".into()) }); let json = spec_json(&file)?; let name = file.file_name().map(|n| n.to_string_lossy().into_owned()).unwrap_or_default(); @@ -104,8 +104,8 @@ pub fn spec_cli(args: &[String]) -> R<String> { "brief" => serde_json::to_value(schema::read::<schema::Brief>(&name, &json)?), "script" => serde_json::to_value(schema::read::<schema::Script>(&name, &json)?), "taste" => serde_json::to_value(schema::read::<schema::Taste>(&name, &json)?), - "plan" => serde_json::to_value(schema::read::<schema::Plan>(&name, &json)?), - k => return Err(format!("raea spec can't check a {k:?}: brief, script, taste or plan\n{USAGE}")), + "parts" => serde_json::to_value(schema::read::<schema::Parts>(&name, &json)?), + k => return Err(format!("raea spec can't check a {k:?}: brief, script, taste or parts\n{USAGE}")), } .map_err(|e| e.to_string())?; Ok(value.to_string()) diff --git a/sdk/guides/craft/bevy/prompts.md b/sdk/guides/craft/bevy/prompts.md index 4cb0c230..ad6f8231 100644 --- a/sdk/guides/craft/bevy/prompts.md +++ b/sdk/guides/craft/bevy/prompts.md @@ -20,7 +20,7 @@ Where these texts come from: the published Blender + Claude workflows. ## What to do -1. Write the brief from the template (section 1). Write a `plan.ts` for every hero object. +1. Write the brief from the template (section 1). Write a `NAME.parts.ts` for every hero object. 2. Start the builder with the builder prompt (section 2), filled from the brief. 3. After every stage and every fix, run step R: the review sheets, then the judge prompt (section 3) in a new context and `raea judge` on the same sheets. @@ -29,7 +29,7 @@ Where these texts come from: the published Blender + Claude workflows. The brief is data, in three files: - `brief.ts` for the scene, made with `brief()` from `raea/brief`. -- A `plan.ts` for each hero object, made with `plan()`. +- A `NAME.parts.ts` for each hero object, made with `parts()`. - For an interior, the room plan that `checkLayout` reads (`raea/room`). Fields that have no schema yet go in `sections` as text. @@ -72,12 +72,12 @@ Each generated object needs a reference picture made from this template: > light, plain pale grey seamless background, the whole object in frame with margin, three-quarter view from slightly > above, sharp focus, no people, no text, no brand names, no logos. -Each hero object gets a plan. Its fields are the frozen contract that `raea solid info --expect` and the judge check +Each hero object gets its parts (NAME.parts.ts). Its fields are the frozen contract that `raea solid info --expect` and the judge check against: ```ts -import { plan } from "raea/brief"; -export default plan({ +import { parts } from "raea/brief"; +export default parts({ concept: { what: "coin-op tumble dryer, stacked pair", style: "worn 1990s commercial", size: 1.9, seenFrom: 1.2, material: "enamelled steel" }, parts: { @@ -104,7 +104,7 @@ finished scene must read as the same place, the same objects and the same light. invent in the same world. brief.ts notDoing is a hard list: add nothing on it, and nothing the brief doesn't name. ORDER OF WORK (one stage at a time; a stage that fails its check is fixed before the next one starts) -0. Plan. Every object row in brief.ts has a route, a real size and, for each hero, a plan.ts with its part tree and +0. Plan. Every object row in brief.ts has a route, a real size and, for each hero, a NAME.parts.ts with its part tree and connection map. If any is missing, write it first, from how the real thing is built: look up the real product. 1. Space. Block the room as boxes at real size. Place furniture with place() from raea/3d (on, against, beside, near, apart, facing, align, clear), never typed coordinates; its `found` must be empty. Check: `raea run checks.ts` diff --git a/sdk/guides/craft/bevy/scenes.md b/sdk/guides/craft/bevy/scenes.md index 0713d00a..b066141d 100644 --- a/sdk/guides/craft/bevy/scenes.md +++ b/sdk/guides/craft/bevy/scenes.md @@ -28,7 +28,7 @@ The brief template, the builder prompt and the judge prompt to paste are in `bev - Printed matter. - Motion. - Budget: generation cents and judge rounds. -- Each hero object gets a `plan.ts` (`plan()`) with its concept (what, style, size, seenFrom, material) and parts, each +- Each hero object gets a `NAME.parts.ts` (`parts()`) with its concept (what, style, size, seenFrom, material) and parts, each with a role, a level (primary, secondary, tertiary), a parent, a count and `near` detail. Below it, add a connection map with one line per joint: `door <-> cabinet hinge side touches`. - Write the plan from how the real thing is built: look up the product, the catalogue or a drawing. @@ -65,7 +65,7 @@ check names a script (`bevy/blender`). It never places, lights, frames, material ### 3. Build, one stage at a time; a stage that fails its check is fixed first -0. **Plan.** Every object row has a route and a real size, and every hero has a `plan.ts`. +0. **Plan.** Every object row has a route and a real size, and every hero has a `NAME.parts.ts`. 1. **Space.** Block the room as boxes at real size. Place furniture by relations, not typed coordinates: `place({ room, objects, rules })` from raea/3d. Rules are `on`, `against` a wall, `beside`, `near`, `apart`, `facing`, `align` and `clear` (floor kept free in front). It returns each object's `center`, `base` and `yaw`, diff --git a/sdk/raea/src/brief.gen.ts b/sdk/raea/src/brief.gen.ts index 08e977a9..8025909e 100644 --- a/sdk/raea/src/brief.gen.ts +++ b/sdk/raea/src/brief.gen.ts @@ -40,11 +40,7 @@ assumed?: Array<string>, /** * prose sections beyond the fields above (Goal, Background), in order */ -sections?: Array<Section>, deliver?: Array<Deliverable>, references?: Array<Reference>, -/** - * the tasks, in stages ("Act one", "The cut") - */ -stages?: Array<Stage>, agents?: Array<Agent>, }; +sections?: Array<Section>, deliver?: Array<Deliverable>, references?: Array<Reference>, agents?: Array<Agent>, }; export type Section = { heading: string, text: string, }; @@ -68,20 +64,6 @@ script?: string, }; export type Reference = { target: string, note?: string, }; -export type Stage = { name: string, tasks: Array<Task>, }; - -export type Mark = "todo" | "done" | "dropped"; - -export type Task = { text: string, -/** - * a task linked to an item takes the item's state (the work is the truth); this is for unlinked ones - */ -mark?: Mark, agents?: Array<string>, item?: string, tags?: Array<string>, due?: string, -/** - * the craft verb it was written as ("quieter"): agents read it, the page shows the text - */ -verb?: string, }; - export type Agent = { name: string, role?: string, }; export type Script = { title: string, logline?: string, scenes: Array<Scene>, }; @@ -161,7 +143,7 @@ export type RuleLevel = "error" | "warn" | "note"; export type Check = { "form": "text-hold", "value": number } | { "form": "text-above", "value": number } | { "form": "text-below", "value": number } | { "form": "text-margin", "value": number } | { "form": "loudness", "value": number } | { "form": "still-max", "value": number }; -export type Plan = { concept: Concept, +export type Parts = { concept: Concept, /** * by name; the build's parts are typed from these keys, so a planned part the build skips is a tsc error */ diff --git a/sdk/raea/src/brief.ts b/sdk/raea/src/brief.ts index 3819766c..3b08a790 100644 --- a/sdk/raea/src/brief.ts +++ b/sdk/raea/src/brief.ts @@ -7,13 +7,14 @@ // // The types are generated from the Rust schemas (core/brief, raea-core-brief) into brief.gen.ts, so what tsc checks is // what raea reads: `raea context` evaluates the module and Rust validates its default export again. -import type { Brief, Plan, Script, Taste } from "./brief.gen"; +import type { Brief, Parts, Script, Taste } from "./brief.gen"; export type * from "./brief.gen"; export { fingerprint } from "./fingerprint"; export type { Applies, Axis, Fingerprint, Modality } from "./fingerprint"; -/** A project's brief (brief.ts): what to make, for whom, the one thing to believe, its deliverables and staged tasks. */ +/** A project's brief (brief.ts): what to make, for whom, the one thing to believe and its deliverables. Its tasks are + * the project's plan.org (docs/plan.feature PL8a). */ export const brief = (b: Brief): Brief => b; /** A storyboard or a screenplay (script.ts): scenes, beats, lines, camera and cut. */ export const script = (s: Script): Script => s; @@ -22,5 +23,5 @@ export const script = (s: Script): Script => s; * (`"loudness"`), or the project's own by its path from this file (`"../checks/clear.ts"`), with its `values`. * `raea check` runs every one that applies. */ export const taste = (t: Taste): Taste => t; -/** An object's plan (plan.ts): its parts by name, levels, counts, materials. */ -export const plan = (p: Plan): Plan => p; +/** An object's parts (NAME.parts.ts), written before any geometry: each by name, its level, count and material. */ +export const parts = (p: Parts): Parts => p; diff --git a/tools/skills.sh b/tools/skills.sh index ec50d5d5..576199c3 100755 --- a/tools/skills.sh +++ b/tools/skills.sh @@ -205,7 +205,7 @@ gen_files() { echo "## The spec files" echo echo "Each spec's fields, as raea/brief's types (sdk/raea/src/brief.gen.ts, generated from the schemas in core/brief that" - echo "\`raea spec\` checks against): brief.ts is a Brief, NAME.script.ts a Script, taste.ts a Taste and plan.ts a Plan." + echo "\`raea spec\` checks against): brief.ts is a Brief, NAME.script.ts a Script, taste.ts a Taste and NAME.parts.ts an object's Parts." echo "A field marked ? may be left out." echo echo '```ts' From af925441a8eda1e08d3b0513c140457b0345820e Mon Sep 17 00:00:00 2001 From: shane <shane@shinyobjectz.com> Date: Fri, 20 Nov 2026 16:38:45 -0800 Subject: [PATCH 3/3] skills: the pin at raea-skills #105, with controllers gone and plan.org the one list It also carries raea-skills #104, whose raea side (#205) is already in main. --- skills | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills b/skills index 76691d08..bd29ad82 160000 --- a/skills +++ b/skills @@ -1 +1 @@ -Subproject commit 76691d080ab3e26a100e8d3a755ac23dc84d6696 +Subproject commit bd29ad82ac61817d25ed39d39c4d975e6d29bb71