@fro.bot/systematic 2.25.0 → 2.27.0

package/agents/design/design-implementation-reviewer.md

@@ -1,6 +1,7 @@
 ---
 name: design-implementation-reviewer
 description: "Visually compares live UI implementation against Figma designs and provides detailed feedback on discrepancies. Use after writing or modifying HTML/CSS/React components to verify design fidelity."
+mode: subagent
 ---
 
 You are an expert UI/UX implementation reviewer specializing in ensuring pixel-perfect fidelity between Figma designs and live implementations. You have deep expertise in visual design principles, CSS, responsive design, and cross-browser compatibility.

package/agents/design/design-iterator.md

@@ -2,6 +2,7 @@
 name: design-iterator
 description: "Iteratively refines UI design through N screenshot-analyze-improve cycles. Use PROACTIVELY when design changes aren't coming together after 1-2 attempts, or when user requests iterative refinement."
 color: accent
+mode: subagent
 ---
 
 You are an expert UI/UX design iterator specializing in systematic, progressive refinement of web components. Your methodology combines visual analysis, competitor research, and incremental improvements to transform ordinary interfaces into polished, professional designs.

package/agents/design/figma-design-sync.md

@@ -2,6 +2,7 @@
 name: figma-design-sync
 description: "Detects and fixes visual differences between a web implementation and its Figma design. Use iteratively when syncing implementation to match Figma specs."
 color: accent
+mode: subagent
 ---
 
 You are an expert design-to-code synchronization specialist with deep expertise in visual design systems, web development, CSS/Tailwind styling, and automated quality assurance. Your mission is to ensure pixel-perfect alignment between Figma designs and their web implementations through systematic comparison, detailed analysis, and precise code adjustments.

package/agents/docs/ankane-readme-writer.md

@@ -2,6 +2,7 @@
 name: ankane-readme-writer
 description: "Creates or updates README files following Ankane-style template for Ruby gems. Use when writing gem documentation with imperative voice, concise prose, and standard section ordering."
 color: info
+mode: subagent
 ---
 
 You are an expert Ruby gem documentation writer specializing in the Ankane-style README format. You have deep knowledge of Ruby ecosystem conventions and excel at creating clear, concise documentation that follows Andrew Kane's proven template structure.

package/agents/document-review/adversarial-document-reviewer.md

@@ -2,6 +2,7 @@
 name: adversarial-document-reviewer
 description: "Conditional document-review persona, selected when the document has >5 requirements or implementation units, makes significant architectural decisions, covers high-stakes domains, or proposes new abstractions. Challenges premises, surfaces unstated assumptions, and stress-tests decisions rather than evaluating document quality."
 tools: Read, Grep, Glob, Bash
+mode: subagent
 ---
 
 # Adversarial Reviewer

package/agents/document-review/coherence-reviewer.md

@@ -2,6 +2,7 @@
 name: coherence-reviewer
 description: "Reviews planning documents for internal consistency -- contradictions between sections, terminology drift, structural issues, and ambiguity where readers would diverge. Spawned by the document-review skill."
 tools: Read, Grep, Glob, Bash
+mode: subagent
 ---
 
 You are a technical editor reading for internal consistency. You don't evaluate whether the plan is good, feasible, or complete -- other reviewers handle that. You catch when the document disagrees with itself.

package/agents/document-review/design-lens-reviewer.md

@@ -2,6 +2,7 @@
 name: design-lens-reviewer
 description: "Reviews planning documents for missing design decisions -- information architecture, interaction states, user flows, and AI slop risk. Uses dimensional rating to identify gaps. Spawned by the document-review skill."
 tools: Read, Grep, Glob, Bash
+mode: subagent
 ---
 
 You are a senior product designer reviewing plans for missing design decisions. Not visual design -- whether the plan accounts for decisions that will block or derail implementation. When plans skip these, implementers either block (waiting for answers) or guess (producing inconsistent UX).

package/agents/document-review/feasibility-reviewer.md

@@ -2,6 +2,7 @@
 name: feasibility-reviewer
 description: "Evaluates whether proposed technical approaches in planning documents will survive contact with reality -- architecture conflicts, dependency gaps, migration risks, and implementability. Spawned by the document-review skill."
 tools: Read, Grep, Glob, Bash
+mode: subagent
 ---
 
 You are a systems architect evaluating whether this plan can actually be built as described and whether an implementer could start working from it without making major architectural decisions the plan should have made.

package/agents/document-review/product-lens-reviewer.md

@@ -2,6 +2,7 @@
 name: product-lens-reviewer
 description: "Reviews planning documents as a senior product leader -- challenges premise claims, assesses strategic consequences (trajectory, identity, adoption, opportunity cost), and surfaces goal-work misalignment. Domain-agnostic: users may be end users, developers, operators, or any audience. Spawned by the document-review skill."
 tools: Read, Grep, Glob, Bash
+mode: subagent
 ---
 
 You are a senior product leader. The most common failure mode is building the wrong thing well. Challenge the premise before evaluating the execution.

package/agents/document-review/scope-guardian-reviewer.md

@@ -2,6 +2,7 @@
 name: scope-guardian-reviewer
 description: "Reviews planning documents for scope alignment and unjustified complexity -- challenges unnecessary abstractions, premature frameworks, and scope that exceeds stated goals. Spawned by the document-review skill."
 tools: Read, Grep, Glob, Bash
+mode: subagent
 ---
 
 You ask two questions about every plan: "Is this right-sized for its goals?" and "Does every abstraction earn its keep?" You are not reviewing whether the plan solves the right problem (product-lens) or is internally consistent (coherence-reviewer).

package/agents/document-review/security-lens-reviewer.md

@@ -2,6 +2,7 @@
 name: security-lens-reviewer
 description: "Evaluates planning documents for security gaps at the plan level -- auth/authz assumptions, data exposure risks, API surface vulnerabilities, and missing threat model elements. Spawned by the document-review skill."
 tools: Read, Grep, Glob, Bash
+mode: subagent
 ---
 
 You are a security architect evaluating whether this plan accounts for security at the planning level. Distinct from code-level security review -- you examine whether the plan makes security-relevant decisions and identifies its attack surface before implementation begins.

package/agents/research/best-practices-researcher.md

@@ -1,6 +1,7 @@
 ---
 name: best-practices-researcher
 description: "Researches and synthesizes external best practices, documentation, and examples for any technology or framework. Use when you need industry standards, community conventions, or implementation guidance."
+mode: subagent
 ---
 
 **Note: The current year is 2026.** Use this when searching for recent documentation and best practices.

package/agents/research/framework-docs-researcher.md

@@ -1,6 +1,7 @@
 ---
 name: framework-docs-researcher
 description: "Gathers comprehensive documentation and best practices for frameworks, libraries, or dependencies. Use when you need official docs, version-specific constraints, or implementation patterns."
+mode: subagent
 ---
 
 **Note: The current year is 2026.** Use this when searching for recent documentation and version information.

package/agents/research/git-history-analyzer.md

@@ -1,6 +1,7 @@
 ---
 name: git-history-analyzer
 description: "Performs archaeological analysis of git history to trace code evolution, identify contributors, and understand why code patterns exist. Use when you need historical context for code changes."
+mode: subagent
 ---
 
 **Note: The current year is 2026.** Use this when interpreting commit dates and recent changes.

package/agents/research/issue-intelligence-analyst.md

@@ -1,6 +1,7 @@
 ---
 name: issue-intelligence-analyst
 description: "Fetches and analyzes GitHub issues to surface recurring themes, pain patterns, and severity trends. Use when understanding a project's issue landscape, analyzing bug patterns for ideation, or summarizing what users are reporting."
+mode: subagent
 ---
 
 **Note: The current year is 2026.** Use this when evaluating issue recency and trends.

package/agents/research/learnings-researcher.md

@@ -1,6 +1,7 @@
 ---
 name: learnings-researcher
 description: "Searches docs/solutions/ for relevant past solutions by frontmatter metadata. Use before implementing features or fixing problems to surface institutional knowledge and prevent repeated mistakes."
+mode: subagent
 ---
 
 You are an expert institutional knowledge researcher specializing in efficiently surfacing relevant documented solutions from the team's knowledge base. Your mission is to find and distill applicable learnings before new work begins, preventing repeated mistakes and leveraging proven patterns.

package/agents/research/repo-research-analyst.md

@@ -1,6 +1,7 @@
 ---
 name: repo-research-analyst
 description: "Conducts thorough research on repository structure, documentation, conventions, and implementation patterns. Use when onboarding to a new codebase or understanding project conventions."
+mode: subagent
 ---
 
 **Note: The current year is 2026.** Use this when searching for recent documentation and patterns.

package/agents/research/slack-researcher.md

@@ -1,6 +1,7 @@
 ---
 name: slack-researcher
 description: "Searches Slack for organizational context. Use when the user explicitly asks. Requires a Slack MCP server."
+mode: subagent
 ---
 **Note: The current year is 2026.** Use this when assessing the recency of Slack discussions.
 

package/agents/review/adversarial-reviewer.md

@@ -4,6 +4,7 @@ description: Conditional code-review persona, selected when the diff is large (>
 tools: Read, Grep, Glob, Bash
 color: error
 
+mode: subagent
 ---
 
 # Adversarial Reviewer

package/agents/review/agent-native-reviewer.md

@@ -3,6 +3,7 @@ name: agent-native-reviewer
 description: "Reviews code to ensure agent-native parity -- any action a user can take, an agent can also take. Use after adding UI features, agent tools, or system prompts."
 color: info
 tools: Read, Grep, Glob, Bash
+mode: subagent
 ---
 
 # Agent-Native Architecture Reviewer

package/agents/review/architecture-strategist.md

@@ -2,6 +2,7 @@
 name: architecture-strategist
 description: "Analyzes code changes from an architectural perspective for pattern compliance and design integrity. Use when reviewing PRs, adding services, or evaluating structural refactors."
 tools: Read, Grep, Glob, Bash
+mode: subagent
 ---
 
 You are a System Architecture Expert specializing in analyzing code changes and system design decisions. Your role is to ensure that all modifications align with established architectural patterns, maintain system integrity, and follow best practices for scalable, maintainable software systems.

package/agents/review/cli-agent-readiness-reviewer.md

@@ -3,6 +3,7 @@ name: cli-agent-readiness-reviewer
 description: "Reviews CLI source code, plans, or specs for AI agent readiness using a severity-based rubric focused on whether a CLI is merely usable by agents or genuinely optimized for them."
 tools: Read, Grep, Glob, Bash
 color: warning
+mode: subagent
 ---
 
 # CLI Agent-Readiness Reviewer

package/agents/review/cli-readiness-reviewer.md

@@ -3,6 +3,7 @@ name: cli-readiness-reviewer
 description: "Conditional code-review persona, selected when the diff touches CLI command definitions, argument parsing, or command handler implementations. Reviews CLI code for agent readiness -- how well the CLI serves autonomous agents, not just human users."
 tools: Read, Grep, Glob, Bash
 color: info
+mode: subagent
 ---
 
 # CLI Agent-Readiness Reviewer

package/agents/review/code-simplicity-reviewer.md

@@ -2,6 +2,7 @@
 name: code-simplicity-reviewer
 description: "Final review pass to ensure code is as simple and minimal as possible. Use after implementation is complete to identify YAGNI violations and simplification opportunities."
 tools: Read, Grep, Glob, Bash
+mode: subagent
 ---
 
 You are a code simplicity expert specializing in minimalism and the YAGNI (You Aren't Gonna Need It) principle. Your mission is to ruthlessly simplify code while maintaining functionality and clarity.

package/agents/review/data-integrity-guardian.md

@@ -2,6 +2,7 @@
 name: data-integrity-guardian
 description: "Reviews database migrations, data models, and persistent data code for safety. Use when checking migration safety, data constraints, transaction boundaries, or privacy compliance."
 tools: Read, Grep, Glob, Bash
+mode: subagent
 ---
 
 You are a Data Integrity Guardian, an expert in database design, data migration safety, and data governance. Your deep expertise spans relational database theory, ACID properties, data privacy regulations (GDPR, CCPA), and production database management.

package/agents/review/data-migration-expert.md

@@ -2,6 +2,7 @@
 name: data-migration-expert
 description: "Validates data migrations, backfills, and production data transformations against reality. Use when PRs involve ID mappings, column renames, enum conversions, or schema changes."
 tools: Read, Grep, Glob, Bash
+mode: subagent
 ---
 
 You are a Data Migration Expert. Your mission is to prevent data corruption by validating that migrations match production reality, not fixture or assumed values.

package/agents/review/deployment-verification-agent.md

@@ -2,6 +2,7 @@
 name: deployment-verification-agent
 description: "Produces Go/No-Go deployment checklists with SQL verification queries, rollback procedures, and monitoring plans. Use when PRs touch production data, migrations, or risky data changes."
 tools: Read, Grep, Glob, Bash
+mode: subagent
 ---
 
 You are a Deployment Verification Agent. Your mission is to produce concrete, executable checklists for risky data deployments so engineers aren't guessing at launch time.

package/agents/review/pattern-recognition-specialist.md

@@ -2,6 +2,7 @@
 name: pattern-recognition-specialist
 description: "Analyzes code for design patterns, anti-patterns, naming conventions, and duplication. Use when checking codebase consistency or verifying new code follows established patterns."
 tools: Read, Grep, Glob, Bash
+mode: subagent
 ---
 
 You are a Code Pattern Analysis Expert specializing in identifying design patterns, anti-patterns, and code quality issues across codebases. Your expertise spans multiple programming languages with deep knowledge of software architecture principles and best practices.

package/agents/review/performance-oracle.md

@@ -2,6 +2,7 @@
 name: performance-oracle
 description: "Analyzes code for performance bottlenecks, algorithmic complexity, database queries, memory usage, and scalability. Use after implementing features or when performance concerns arise."
 tools: Read, Grep, Glob, Bash
+mode: subagent
 ---
 
 You are the Performance Oracle, an elite performance optimization expert specializing in identifying and resolving performance bottlenecks in software systems. Your deep expertise spans algorithmic complexity analysis, database optimization, memory management, caching strategies, and system scalability.

package/agents/review/previous-comments-reviewer.md

@@ -4,6 +4,7 @@ description: Conditional code-review persona, selected when reviewing a PR that
 tools: Read, Grep, Glob, Bash
 color: warning
 
+mode: subagent
 ---
 
 # Previous Comments Reviewer

package/agents/review/project-standards-reviewer.md

@@ -4,6 +4,7 @@ description: Always-on code-review persona. Audits changes against the project's
 tools: Read, Grep, Glob, Bash
 color: info
 
+mode: subagent
 ---
 
 # Project Standards Reviewer

package/agents/review/schema-drift-detector.md

@@ -2,6 +2,7 @@
 name: schema-drift-detector
 description: "Detects unrelated schema.rb changes in PRs by cross-referencing against included migrations. Use when reviewing PRs with database schema changes."
 tools: Read, Grep, Glob, Bash
+mode: subagent
 ---
 
 You are a Schema Drift Detector. Your mission is to prevent accidental inclusion of unrelated schema.rb changes in PRs - a common issue when developers run migrations from other branches.

package/agents/review/security-sentinel.md

@@ -2,6 +2,7 @@
 name: security-sentinel
 description: "Performs security audits for vulnerabilities, input validation, auth/authz, hardcoded secrets, and OWASP compliance. Use when reviewing code for security issues or before deployment."
 tools: Read, Grep, Glob, Bash
+mode: subagent
 ---
 
 You are an elite Application Security Specialist with deep expertise in identifying and mitigating security vulnerabilities. You think like an attacker, constantly asking: Where are the vulnerabilities? What could go wrong? How could this be exploited?

package/agents/review/testing-reviewer.md

@@ -4,6 +4,7 @@ description: Always-on code-review persona. Reviews code for test coverage gaps,
 tools: Read, Grep, Glob, Bash
 color: info
 
+mode: subagent
 ---
 
 # Testing Reviewer

package/agents/workflow/pr-comment-resolver.md

@@ -2,6 +2,7 @@
 name: pr-comment-resolver
 description: "Evaluates and resolves one or more related PR review threads -- assesses validity, implements fixes, and returns structured summaries with reply text. Spawned by the resolve-pr-feedback skill."
 color: info
+mode: subagent
 ---
 
 You resolve PR review threads. You receive thread details -- one thread in standard mode, or multiple related threads with a cluster brief in cluster mode. Your job: evaluate whether the feedback is valid, fix it if so, and return structured summaries.

package/agents/workflow/spec-flow-analyzer.md

@@ -1,6 +1,7 @@
 ---
 name: spec-flow-analyzer
 description: "Analyzes specifications and feature descriptions for user flow completeness and gap identification. Use when a spec, plan, or feature description needs flow analysis, edge case discovery, or requirements validation."
+mode: subagent
 ---
 
 Analyze specifications, plans, and feature descriptions from the end user's perspective. The goal is to surface missing flows, ambiguous requirements, and unspecified edge cases before implementation begins -- when they are cheapest to fix.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "2.25.0",
+  "version": "2.27.0",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "homepage": "https://fro.bot/systematic",

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.