@fro.bot/systematic 2.24.0 → 2.26.0

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   findCommandsInDir,
   findSkillsInDir,
   getConfigPaths
-} from "./index-175fc4yn.js";
+} from "./index-3q3ns1xh.js";
 
 // src/cli.ts
 import fs from "fs";

package/dist/index.js

@@ -13,7 +13,7 @@ import {
   loadConfig,
   loadConfigWithSources,
   parseFrontmatter
-} from "./index-175fc4yn.js";
+} from "./index-3q3ns1xh.js";
 
 // src/index.ts
 import fs5 from "fs";

package/dist/lib/frontmatter.d.ts

@@ -4,6 +4,18 @@ export interface FrontmatterResult<T = Record<string, unknown>> {
     hadFrontmatter: boolean;
     parseError: boolean;
 }
+/**
+ * Returns the raw YAML text between the opening and closing `---` delimiters,
+ * or `null` when the content has no frontmatter block.
+ *
+ * Scope: flat top-level frontmatter only. Nested/indented mapping values are
+ * returned verbatim as part of the block — callers that scan individual lines
+ * (e.g. parse-safety checks) must skip indented lines themselves.
+ *
+ * Handles LF and CRLF line endings. The closing `---` does not need a trailing
+ * newline (handles files that end immediately after the delimiter).
+ */
+export declare function extractFrontmatterBlock(content: string): string | null;
 /**
  * Parses YAML frontmatter from Markdown content.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "2.24.0",
+  "version": "2.26.0",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "homepage": "https://fro.bot/systematic",
@@ -37,7 +37,7 @@
     "docs:build": "bun run docs:generate && bun run --cwd docs build",
     "docs:preview": "bun run --cwd docs preview",
     "docs:verify": "bun install --frozen-lockfile && bun run --cwd docs playwright install --with-deps chromium && bun run docs:build",
-    "docs:generate": "bun docs/scripts/transform-content.ts && bun scripts/generate-config-schema.ts && bun docs/scripts/generate-config-reference.ts",
+    "docs:generate": "bun docs/scripts/generate-stats.ts && bun docs/scripts/transform-content.ts && bun scripts/generate-config-schema.ts && bun docs/scripts/generate-config-reference.ts",
     "schema:generate": "bun scripts/generate-config-schema.ts",
     "schema:drift": "bun scripts/generate-config-schema.ts --check",
     "registry:build": "bun scripts/build-registry.ts",
@@ -65,9 +65,9 @@
     "@opencode-ai/plugin": "^1.1.30"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.4.15",
-    "@opencode-ai/plugin": "1.15.10",
-    "@opencode-ai/sdk": "1.15.10",
+    "@biomejs/biome": "2.4.16",
+    "@opencode-ai/plugin": "1.15.13",
+    "@opencode-ai/sdk": "1.15.13",
     "@semantic-release/exec": "7.1.0",
     "@types/bun": "latest",
     "@types/js-yaml": "4.0.9",

package/skills/ce-brainstorm/SKILL.md

@@ -179,14 +179,31 @@ If relevant, call out whether the choice is:
 - Extend an existing capability
 - Build something net new
 
+### Phase 2.5: Synthesis Summary
+
+**STOP. Before composing the synthesis, read `references/synthesis-summary.md`.** The two-stage shape (internal three-bucket draft → chat-time scoping synthesis), the Path A / Path B gate, the four scoping synthesis sections with their keep tests, the tier-aware bullet budget with re-cut rule, anti-pattern guidance, soft-cut behavior, self-redirect support, and headless-mode routing all live there. Composing a synthesis without these rules loaded reliably produces malformed output — pasting the full internal three-bucket draft verbatim into chat, implementation-detail leakage into the scoping synthesis, the proposal-pitch anti-pattern. **Each scoping synthesis bullet must pass the affirmability test (can the user evaluate this without reading code?) AND the detail test (1–2 lines max, conversational not documentary); over-share and over-detail are the failure modes to avoid.** This is not optional supplementary reading; it is the source of truth for how the phase behaves.
+
+Surface a scoping synthesis to the user before Phase 3 writes the requirements doc — the user's last opportunity to correct scope before the artifact lands. **Phase 2.5 is the only scope gate in this workflow.** The scoping synthesis is shaped like what two product collaborators would confirm before writing a PRD, not like a comprehensive audit or a one-line preview.
+
+Fires for **all tiers** including Lightweight. Skip Phase 2.5 entirely on the Phase 0.1b non-software (universal-brainstorming) route.
+
+**Path A vs Path B:** the scoping synthesis shape depends on TWO signals — whether any blocking question fired AND what tier Phase 0.3 classified the scope as.
+
+- **Path A — no blocking questions fired AND tier is Lightweight**: announce-mode. Emit "What we're building" prose only (1–3 sentences), then proceed to Phase 3 doc-write in the same turn. No other sections, no confirmation question. Do NOT end the turn waiting for acknowledgment. The user can revise after the doc lands if the shape is wrong — Lightweight Path A docs are short, post-hoc revision is cheap.
+- **Path B — at least one blocking question fired, OR tier is Standard / Deep-feature / Deep-product**: full tier-aware scoping synthesis with confirmation gate. Two scenarios fire Path B: (a) the user invested answer-time during dialogue, or (b) the user pre-loaded substantive scope content (Phase 0.2 fast-path with a richly-specified opening prompt). Either way, the substance earns a real checkpoint. Confirmation is unconditional even when zero call-outs survive the keep test.
+
+**Why the tier guard on Path A**: Phase 0.2's fast path serves two very different cases — a tight one-liner that needs no dialogue ("fix the typo on line 47") and a richly pre-loaded brainstorm context that ALSO needs no dialogue because the user pre-stated everything. Without the tier guard, both route to Path A and the pre-loaded case gets a 1-sentence checkpoint for what may be 20+ items worth of scope. Tier-classifying Phase 0.3 distinguishes the two — pre-loaded substance makes the tier Standard or Deep, which then routes to Path B.
+
 ### Phase 3: Capture the Requirements
 
-Write or update a requirements document only when the conversation produced durable decisions worth preserving. Read `references/requirements-capture.md` for the document template, formatting rules, visual aid guidance, and completeness checks.
+Write or update a requirements document only when the conversation produced durable decisions worth preserving. Read `references/requirements-capture.md` for the document template, formatting rules, visual aid guidance, and completeness checks. Read `references/brainstorm-sections.md` for metadata field contracts and ID conventions. Read `references/markdown-rendering.md` for markdown presentation principles.
 
 For **Lightweight** brainstorms, keep the document compact. Skip document creation when the user only needs brief alignment and no durable decisions need to be preserved.
 
 ### Phase 3.5: Document Review
 
+**This is a quality and format review of the written artifact — not a second scope negotiation.** Scope was confirmed at Phase 2.5; Phase 3.5 checks that the written doc faithfully reflects that confirmed scope and meets quality standards. Do not re-open scope decisions here.
+
 When a requirements document was created or updated, run the `document-review` skill on it before presenting handoff options. Pass the document path as the argument.
 
 If document-review returns findings that were auto-applied, note them briefly when presenting handoff options. If residual P0/P1 findings were surfaced, mention them so the user can decide whether to address them before proceeding.

package/skills/ce-brainstorm/references/brainstorm-sections.md

@@ -0,0 +1,50 @@
+# Brainstorm Sections
+
+This reference describes the rendering and ordering conventions for brainstorm
+requirements documents. It does NOT prescribe which sections exist or what they
+must contain — section inventory, content rules, and the document template live
+in `references/requirements-capture.md`.
+
+Rendering is handled by `references/markdown-rendering.md`.
+
+## Brainstorm metadata fields
+
+Every brainstorm carries a small set of stable metadata fields that
+downstream tooling depends on. The contract is format-independent: these
+fields appear as YAML frontmatter at the top of the file. Field names and
+semantics are stable so consumers can locate them without knowing which
+session produced the brainstorm.
+
+### Required
+
+- **`date`** — creation date in ISO 8601 (`YYYY-MM-DD`), ASCII digits only.
+  Used in the filename (`docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md`).
+- **`topic`** — kebab-case slug identifying the brainstorm subject (e.g.,
+  `surface-scope-earlier`, `demo-reel-local-save`). Used in the filename
+  alongside `date` and as the resume-detection key when `ce-brainstorm`'s
+  Phase 0.1 scans `docs/brainstorms/` for an existing artifact to continue.
+
+### Status flip does not apply to brainstorm
+
+Unlike plans, brainstorm artifacts have no `status` field — there is no
+`active → completed` lifecycle. A brainstorm is a one-time output that
+downstream consumers (`ce-plan`, `document-review`) reference via the plan's
+`origin:` field.
+
+### Field-name stability
+
+Field names are stable across brainstorm revisions — never rename a field
+or repurpose its semantics. Agents composing new brainstorms MUST use these
+exact names; adding new fields is fine, but renaming `topic` to `subject`
+or `date` to `created` breaks filename construction and resume detection.
+
+> **Section inventory, content rules, and the Summary vs Problem Frame discipline are owned by `references/requirements-capture.md`; this file covers rendering conventions and metadata contracts only.**
+
+## Rendering
+
+The format-specific reference describes how to render these sections:
+
+- **Markdown rendering:** `references/markdown-rendering.md`
+
+This reference (`brainstorm-sections.md`) is about rendering conventions and
+metadata contracts; section content rules live in `references/requirements-capture.md`.

package/skills/ce-brainstorm/references/markdown-rendering.md

@@ -0,0 +1,202 @@
+# Markdown Rendering
+
+This is a format-rendering reference — it describes how to render any
+artifact in markdown, independent of which skill is producing it.
+
+It is paired with a section contract (`references/brainstorm-sections.md`)
+that describes *what* the artifact contains. This reference describes *how*
+markdown specifically presents it.
+
+## Hard invariants
+
+These hold regardless of which skill produced the artifact.
+
+- **YAML frontmatter at the top of the file.** Standard `---` delimited block
+  containing the artifact's stable metadata (title, status, date, type, etc.
+  — exact fields are per-skill, defined in the section contract). Editable
+  in place; tools and agents that do status flips (`active → completed`)
+  update the YAML directly.
+- **ASCII identifiers in anchors.** Markdown headings auto-generate anchors
+  from the heading text. Keep headings ASCII so anchors are predictable
+  (`#implementation-units`, not `#implementación-units`).
+- **Repo-relative paths for file references.** Always. Never absolute paths
+  — they break portability across machines, worktrees, teammates.
+- **No HTML mixed in.** Keep the markdown pure. No `<div>`, no `<details>`,
+  no inline `<style>`. Markdown stays markdown.
+
+## Format principles
+
+These shape what "good" markdown looks like; the agent applies them per
+artifact based on content shape.
+
+### ID prefix format
+
+Stable IDs (R, U, A, F, AE, KTD) appear as plain prefixes at the start of
+the bullet or heading — do NOT bold the prefix. The prefix is visually
+distinctive on its own; bolding it inflates visual noise.
+
+```markdown
+- R1. The plan returns paginated sessions.   ← right
+- **R1.** The plan returns paginated sessions.   ← wrong (bolded prefix)
+```
+
+Same applies to unit headings: `### U1. Cloak detection in preflight contract`.
+
+### Content shape: prose vs bullets vs tables
+
+The same content can be rendered three ways; the agent picks per content
+shape, not by template default.
+
+- **Prose** when the content has narrative flow (motivation, decision
+  rationale, problem framing). Bullets fragment narrative into
+  disconnected pieces.
+- **Bullets** when items share a parallel shape but each carries enough
+  prose to not fit a table cell.
+- **Tables** when 5+ items share uniform structure (`ID + body`,
+  `name + value`, `decision + rationale`, `risk + mitigation`). Tables
+  scan faster at that scale and unlock additional columns (status,
+  traceability, severity) that bullets can't accommodate cleanly.
+
+The test: which shape would a reader scan fastest for this content? If
+items have parallel structure and 5+ instances, table. If items are 3-5
+and each has a few lines of prose, bullets. If the content is a single
+narrative thought, prose.
+
+### Bold leader labels within bullets
+
+When a bullet has substructure that benefits from named fields (Key Flows
+with Trigger / Actors / Steps / Outcome, Acceptance Examples with Covers
+/ Given / When / Then), use bold leader labels at the start of nested
+bullets — not deeper heading levels.
+
+```markdown
+- F1. Anonymous capture
+  - **Trigger:** Agent enters Step 2a with no session.
+  - **Actors:** A1, A2
+  - **Steps:** Preflight detects cloak; agent launches; capture proceeds.
+  - **Covered by:** R1, R2, R5
+```
+
+This gives the bullet structure without needing H4/H5 headings that would
+clutter the doc and break TOC generation.
+
+### Section separators
+
+For substantial artifacts, use horizontal rules (`---`) between top-level
+H2 sections. Omit for short docs where separators would dominate.
+
+### Tables for genuinely comparative info only
+
+Use tables for the uniform-shape case in "Content shape" above. Don't use
+tables to render content lists that are really bullets — markdown tables
+are noisier in raw form and worse for diffs.
+
+## Section anatomy
+
+How section types commonly render in markdown. These are patterns, not
+contracts — the agent picks the shape that fits the content.
+
+- **Summary / Problem Frame** — prose paragraphs.
+- **Requirements** — bullets with `R<N>.` prefix. When requirements span
+  more than one concern, grouping under bold inline headers is the default
+  shape, not optional polish (group by capability, not by discussion order);
+  render a flat list only when every requirement is about the same thing.
+  When requirements have status, traceability, or severity that warrant
+  additional columns, escalate to a table.
+- **Implementation Units** — H3 heading per unit with `U<N>.` prefix.
+  Fields (Goal, Files, Patterns, Test Scenarios, Verification) render as
+  bullets with bold leader labels, or as sub-headings if the field has
+  multi-paragraph content.
+- **Key Technical Decisions** — bullets with bold decision name + prose
+  rationale, or numbered KTD-N pattern when traceability matters.
+- **Key Flows / Acceptance Examples** — bullets with bold leader labels
+  (Trigger / Actors / Steps / Outcome / Covers / Given-When-Then).
+- **Scope Boundaries** — bullets, optionally split into "Deferred for
+  later" / "Outside this product's identity" sub-headings when the
+  positioning distinction matters.
+
+The agent picks more elaborate or simpler shapes based on what each
+specific artifact's content needs.
+
+## Diagrams
+
+When the section contract calls for a diagram (architecture, sequence,
+flowchart, state machine, swim lane, data-flow), markdown renders it as
+a fenced mermaid block:
+
+```markdown
+` ``mermaid
+flowchart TB
+  A[Start] --> B{Decision}
+  B -->|yes| C[Action]
+  B -->|no| D[Other action]
+` ``
+```
+
+(`TB` direction default — keeps diagrams narrow in source view and in
+narrow rendered viewports.)
+
+For quantitative comparisons (bar charts, scatter plots) markdown has no
+native equivalent — use a table with the data and let prose or caption
+carry the interpretation.
+
+## Inline code and code blocks
+
+- **Inline code** for identifiers (variable names, function names,
+  flag names, file paths, IDs that aren't section anchors).
+- **Fenced code blocks** with language tag for code, shell commands,
+  API request/response samples. Always specify the language for syntax
+  highlighting and accessibility.
+
+```markdown
+The flag `--cdp-url` accepts a URL.
+
+` ``bash
+browser-use --cdp-url http://localhost:9222
+` ``
+```
+
+## No process exhaust
+
+Engineering process metadata stays out of the artifact:
+
+- No "captured at Phase X" notes
+- No `## Next Steps` pointing to the next skill
+- No italic provenance lines ("*Brainstorm completed 2026-05-13*")
+- No engineering-flow shepherding ("Now read this file:", "Next, run that
+  command:")
+
+This information belongs in commit messages, tool output, and agent
+transcripts — not in the artifact a reader returns to weeks later.
+
+## Frontmatter shape
+
+Per-skill frontmatter fields are defined in each skill's section contract
+(`references/brainstorm-sections.md` lists brainstorm frontmatter). Common rules:
+
+- YAML at the top of the file, delimited by `---` on its own line above
+  and below.
+- Field names in lowercase snake_case (`status`, `created_at`, not
+  `Status`, `CreatedAt`).
+- **Status lifecycle is per-contract.** When the section contract
+  defines a `status` field with a lifecycle (plans use
+  `active → completed`, flipped by ce-work at shipping time via direct
+  YAML edit), it is editable in place. When the section contract does
+  not define a status lifecycle (brainstorms have no `active → completed`
+  flip — they are upstream of plans and referenced via the plan's
+  `origin:`), do not introduce one.
+- Stable across artifact revisions — never rename or repurpose a field.
+
+## Post-write audit
+
+Before declaring the markdown file written, scan it for these common
+slips:
+
+- All stable IDs are plain-prefix format, not bolded.
+- No HTML elements mixed in.
+- All file paths are repo-relative.
+- Horizontal rule separators between H2s (for Standard / Deep artifacts).
+- No process exhaust (Phase X notes, Next Steps pointers, provenance
+  lines).
+- Tables only where 5+ uniform-shape items justify them.
+- Frontmatter has all the per-skill required fields with reasonable values.

package/skills/ce-brainstorm/references/requirements-capture.md

@@ -24,6 +24,7 @@ The requirements document is for product definition and scope control. Do **not*
 | Key Decisions | Include when material | Include when material | Include when material |
 | Dependencies / Assumptions | Include when material | Include when material | Include when material |
 | Outstanding Questions | Include when material | Include when material | Include when material |
+| Sources / Research | Include when material | Include when material | Include when material |
 
 ## Summary vs Problem Frame discipline
 
@@ -48,6 +49,25 @@ In the truly-trivial Lightweight case where Summary is skipped (synthesis ≤ 2
 
 **Acceptance Examples** — include when a requirement's behavior is hard to pin down without a concrete scenario. **Always include AEs covering behavioral-conditional requirements** — any requirement framed as "When X, Y" or "If X, Y" — regardless of tier. Conditional framing signals state-dependent behavior, which is exactly where prose alone leaves implicit ambiguity (e.g., "When `--quiet` is set, errors continue to surface" — does that include warnings? does it include binary-side errors? AE pins it down). Each example disambiguates one or more requirements via a `Covers: R-IDs` back-reference. Non-conditional requirements may be omitted unless ambiguity surfaces in review; the section is not exhaustive.
 
+**Sources / Research** — surface research that orients the planner or justifies framing choices. The test: *"if I were the planner reading this cold, would this breadcrumb help me make better choices?"* Yes → surface (code locations, external docs, RFCs, constraints, prior plans — the category is inclusive, not enumerated). Process exhaust (reading the user's prompt, glancing at obvious files) → omit.
+
+## Prose economy
+
+A section can be material and still be written loosely — the failure mode is a material section padded into a wall of text where contradictions hide and a downstream agent loses the thread. Length that earns its place is fine; wordiness around that length is not.
+
+Hold every kept section to these:
+
+- **One idea per sentence.** A Summary is a handful of sentences, not one sentence with five semicolons and four parentheticals. If a sentence needs a second parenthetical to stay true, split it.
+- **A requirement is one sentence of intent plus at most one qualifier.** When a requirement would specify two outcomes ("either A or B, planning decides"), state the intent and send the fork to Outstanding Questions — don't write both arms in full inside the requirement.
+- **Cut hedges and intensifiers.** "Critically", "deliberately", "explicitly", "genuinely", "actually", "simply" carry nothing a downstream agent acts on.
+- **Prefer the verb to the nominalization.** "Demote the grid", not "the demotion of the grid is the deliberate change in this brief".
+
+Precision is not padding: keep domain terms, conditionals, and exact thresholds verbatim. Economy targets the connective tissue around them, never the precision itself.
+
+**Resolve in place; don't stratify.** When a later decision answers a parked question or supersedes earlier text, rewrite or remove the original entry — don't append a separate "resolutions" layer that leaves the superseded text standing. Version control holds the history. Stacked question/resolution strata double the reading surface and hide which text is live.
+
+**Named test, run before the doc is declared written:** could a reader find a contradiction in each section in one pass? A sentence carrying more than one parenthetical, or a requirement specifying two outcomes, fails the test — split it or defer it.
+
 ## Template
 
 Use this template and omit sections per the matrix above. At Deep-product tier, keep the Scope Boundaries split. At other tiers, use the single Scope Boundaries list.