@fro.bot/systematic 2.3.3 → 2.4.0

package/skills/document-review/SKILL.md

@@ -1,17 +1,41 @@
 ---
 name: document-review
 description: Review requirements or plan documents using parallel persona agents that surface role-specific issues. Use when a requirements document or plan document exists and the user wants to improve it.
+argument-hint: "[mode:headless] [path/to/document.md]"
 ---
 
 # Document Review
 
 Review requirements or plan documents through multi-persona analysis. Dispatches specialized reviewer agents in parallel, auto-fixes quality issues, and presents strategic questions for user decision.
 
+## Phase 0: Detect Mode
+
+Check the skill arguments for `mode:headless`. Arguments may contain a document path, `mode:headless`, or both. Tokens starting with `mode:` are flags, not file paths -- strip them from the arguments and use the remaining token (if any) as the document path for Phase 1.
+
+If `mode:headless` is present, set **headless mode** for the rest of the workflow.
+
+**Headless mode** changes the interaction model, not the classification boundaries. Document-review still applies the same judgment about what has one clear correct fix vs. what needs user judgment. The only difference is how non-auto findings are delivered:
+- `auto` fixes are applied silently (same as interactive)
+- `present` findings are returned as structured text for the caller to handle -- no question prompts, no interactive approval
+- Phase 5 returns immediately with "Review complete" (no refine/complete question)
+
+The caller receives findings with their original classifications intact and decides what to do with them.
+
+Callers invoke headless mode by including `mode:headless` in the skill arguments, e.g.:
+```
+Skill("systematic:document-review", "mode:headless docs/plans/my-plan.md")
+```
+
+
+If `mode:headless` is not present, the skill runs in its default interactive mode with no behavior change.
+
 ## Phase 1: Get and Analyze Document
 
 **If a document path is provided:** Read it, then proceed.
 
-**If no document is specified:** Ask which document to review, or find the most recent in `docs/brainstorms/` or `docs/plans/` using a file-search/glob tool (e.g., Glob in OpenCode).
+**If no document is specified (interactive mode):** Ask which document to review, or find the most recent in `docs/brainstorms/` or `docs/plans/` using a file-search/glob tool (e.g., Glob in OpenCode).
+
+**If no document is specified (headless mode):** Output "Review failed: headless mode requires a document path. Re-invoke with: Skill(\"systematic:document-review\", \"mode:headless <path>\")" without dispatching agents.
 
 ### Classify Document Type
 
@@ -23,11 +47,19 @@ After reading, classify the document:
 
 Analyze the document content to determine which conditional personas to activate. Check for these signals:
 
-**product-lens** -- activate when the document contains:
-- User-facing features, user stories, or customer-focused language
-- Market claims, competitive positioning, or business justification
-- Scope decisions, prioritization language, or priority tiers with feature assignments
-- Requirements with user/customer/business outcome focus
+**product-lens** -- activate when the document makes challengeable claims about what to build and why, or when the proposed work carries strategic weight beyond the immediate problem. The system's users may be end users, developers, operators, maintainers, or any other audience -- the criteria are domain-agnostic. Check for either leg:
+
+*Leg 1 — Premise claims:* The document stakes a position on what to build or why that a knowledgeable stakeholder could reasonably challenge -- not merely describing a task or restating known requirements:
+- Problem framing where the stated need is non-obvious or debatable, not self-evident from existing context
+- Solution selection where alternatives plausibly exist (implicit or explicit)
+- Prioritization decisions that explicitly rank what gets built vs deferred
+- Goal statements that predict specific user outcomes, not just restate constraints or describe deliverables
+
+*Leg 2 — Strategic weight:* The proposed work could affect system trajectory, user perception, or competitive positioning, even if the premise is sound:
+- Changes that shape how the system is perceived or what it becomes known for
+- Complexity or simplicity bets that affect adoption, onboarding, or cognitive load
+- Work that opens or closes future directions (path dependencies, architectural commitments)
+- Opportunity cost implications -- building this means not building something else
 
 **design-lens** -- activate when the document contains:
 - UI/UX references, frontend components, or visual design language
@@ -48,6 +80,12 @@ Analyze the document content to determine which conditional personas to activate
 - Scope boundary language that seems misaligned with stated goals
 - Goals that don't clearly connect to requirements
 
+**adversarial** -- activate when the document contains:
+- More than 5 distinct requirements or implementation units
+- Explicit architectural or scope decisions with stated rationale
+- High-stakes domains (auth, payments, data migrations, external integrations)
+- Proposals of new abstractions, frameworks, or significant architectural patterns
+
 ## Phase 2: Announce and Dispatch Personas
 
 ### Announce the Review Team
@@ -73,15 +111,16 @@ Add activated conditional personas:
 - `systematic:document-review:design-lens-reviewer`
 - `systematic:document-review:security-lens-reviewer`
 - `systematic:document-review:scope-guardian-reviewer`
+- `systematic:document-review:adversarial-document-reviewer`
 
 ### Dispatch
 
-Dispatch all agents in **parallel** using the platform's task/agent tool (e.g., Agent tool in OpenCode, spawn in Codex). Each agent receives the prompt built from the [subagent template](./references/subagent-template.md) with these variables filled:
+Dispatch all agents in **parallel** using the platform's task/agent tool (e.g., Agent tool in OpenCode, spawn in Codex). Omit the `mode` parameter so the user's configured permission settings apply. Each agent receives the prompt built from the subagent template included below with these variables filled:
 
 | Variable | Value |
 |----------|-------|
 | `{persona_file}` | Full content of the agent's markdown file |
-| `{schema}` | Content of [findings-schema.json](./references/findings-schema.json) |
+| `{schema}` | Content of the findings schema included below |
 | `{document_type}` | "requirements" or "plan" from Phase 1 classification |
 | `{document_path}` | Path to the document |
 | `{document_content}` | Full text of the document |
@@ -90,112 +129,20 @@ Pass each agent the **full document** -- do not split into sections.
 
 **Error handling:** If an agent fails or times out, proceed with findings from agents that completed. Note the failed agent in the Coverage section. Do not block the entire review on a single agent failure.
 
-**Dispatch limit:** Even at maximum (6 agents), use parallel dispatch. These are document reviewers with bounded scope reading a single document -- parallel is safe and fast.
-
-## Phase 3: Synthesize Findings
-
-Process findings from all agents through this pipeline. **Order matters** -- each step depends on the previous.
-
-### 3.1 Validate
-
-Check each agent's returned JSON against [findings-schema.json](./references/findings-schema.json):
-- Drop findings missing any required field defined in the schema
-- Drop findings with invalid enum values
-- Note the agent name for any malformed output in the Coverage section
-
-### 3.2 Confidence Gate
-
-Suppress findings below 0.50 confidence. Store them as residual concerns for potential promotion in step 3.4.
-
-### 3.3 Deduplicate
-
-Fingerprint each finding using `normalize(section) + normalize(title)`. Normalization: lowercase, strip punctuation, collapse whitespace.
-
-When fingerprints match across personas:
-- If the findings recommend **opposing actions** (e.g., one says cut, the other says keep), do not merge -- preserve both for contradiction resolution in 3.5
-- Otherwise merge: keep the highest severity, keep the highest confidence, union all evidence arrays, note all agreeing reviewers (e.g., "coherence, feasibility")
+**Dispatch limit:** Even at maximum (7 agents), use parallel dispatch. These are document reviewers with bounded scope reading a single document -- parallel is safe and fast.
 
-### 3.4 Promote Residual Concerns
+## Phases 3-5: Synthesis, Presentation, and Next Action
 
-Scan the residual concerns (findings suppressed in 3.2) for:
-- **Cross-persona corroboration**: A residual concern from Persona A overlaps with an above-threshold finding from Persona B. Promote at P2 with confidence 0.55-0.65.
-- **Concrete blocking risks**: A residual concern describes a specific, concrete risk that would block implementation. Promote at P2 with confidence 0.55.
+After all dispatched agents return, read `references/synthesis-and-presentation.md` for the synthesis pipeline (validate, gate, dedup, promote, resolve contradictions, route by autofix class), auto-fix application, finding presentation, and next-action menu. Do not load this file before agent dispatch completes.
 
-### 3.5 Resolve Contradictions
-
-When personas disagree on the same section:
-- Create a **combined finding** presenting both perspectives
-- Set `autofix_class: present`
-- Frame as a tradeoff, not a verdict
-
-Specific conflict patterns:
-- Coherence says "keep for consistency" + scope-guardian says "cut for simplicity" -> combined finding, let user decide
-- Feasibility says "this is impossible" + product-lens says "this is essential" -> P1 finding framed as a tradeoff
-- Multiple personas flag the same issue -> merge into single finding, note consensus, increase confidence
-
-### 3.6 Route by Autofix Class
-
-| Autofix Class | Route |
-|---------------|-------|
-| `auto` | Apply automatically -- local deterministic fix (terminology, formatting, cross-references) |
-| `present` | Present to user for judgment |
-
-Demote any `auto` finding that lacks a `suggested_fix` to `present` -- the orchestrator cannot apply a fix without concrete replacement text.
-
-### 3.7 Sort
-
-Sort findings for presentation: P0 -> P1 -> P2 -> P3, then by confidence (descending), then by document order (section position).
-
-## Phase 4: Apply and Present
-
-### Apply Auto-fixes
-
-Apply all `auto` findings to the document in a **single pass**:
-- Edit the document inline using the platform's edit tool
-- Track what was changed for the "Auto-fixes Applied" section
-- Do not ask for approval -- these are unambiguously correct (terminology fixes, formatting, cross-references)
-
-### Present Remaining Findings
-
-Present all other findings to the user using the format from [review-output-template.md](./references/review-output-template.md):
-- Group by severity (P0 -> P3)
-- Include the Coverage table showing which personas ran
-- Show auto-fixes that were applied
-- Include residual concerns and deferred questions if any
-
-Brief summary at the top: "Applied N auto-fixes. M findings to consider (X at P0/P1)."
-
-### Protected Artifacts
-
-During synthesis, discard any finding that recommends deleting or removing files in:
-- `docs/brainstorms/`
-- `docs/plans/`
-- `docs/solutions/`
-
-These are pipeline artifacts and must not be flagged for removal.
-
-## Phase 5: Next Action
-
-Use the platform's blocking question tool when available (question in OpenCode, request_user_input in Codex, ask_user in Gemini). Otherwise present numbered options and wait for the user's reply.
-
-Offer:
-
-1. **Refine again** -- another review pass
-2. **Review complete** -- document is ready
-
-After 2 refinement passes, recommend completion -- diminishing returns are likely. But if the user wants to continue, allow it.
-
-Return "Review complete" as the terminal signal for callers.
+---
 
-## What NOT to Do
+## Included References
 
-- Do not rewrite the entire document
-- Do not add new sections or requirements the user didn't discuss
-- Do not over-engineer or add complexity
-- Do not create separate review files or add metadata sections
-- Do not modify any of the 4 caller skills (ce-brainstorm, ce-plan, ce-plan-beta, deepen-plan-beta)
+### Subagent Template
 
-## Iteration Guidance
+@./references/subagent-template.md
 
-On subsequent passes, re-dispatch personas and re-synthesize. The auto-fix mechanism and confidence gating prevent the same findings from recurring once fixed. If findings are repetitive across passes, recommend completion.
+### Findings Schema
 
+@./references/findings-schema.json

package/skills/document-review/references/findings-schema.json

@@ -82,28 +82,5 @@
       "description": "Questions that should be resolved in a later workflow stage (planning, implementation)",
       "items": { "type": "string" }
     }
-  },
-
-  "_meta": {
-    "confidence_thresholds": {
-      "suppress": "Below 0.50 -- do not report. Finding is speculative noise.",
-      "flag": "0.50-0.69 -- include only when the persona's calibration says the issue is actionable at that confidence.",
-      "report": "0.70+ -- report with full confidence."
-    },
-    "severity_definitions": {
-      "P0": "Contradictions or gaps that would cause building the wrong thing. Must fix before proceeding.",
-      "P1": "Significant gap likely hit during planning or implementation. Should fix.",
-      "P2": "Moderate issue with meaningful downside. Fix if straightforward.",
-      "P3": "Minor improvement. User's discretion."
-    },
-    "autofix_classes": {
-      "_principle": "Autofix class is independent of severity. A P1 finding can be auto if the fix is obvious. The test: is there one clear correct fix, or does resolving this require judgment?",
-      "auto": "One clear correct fix -- applied silently. Includes both internal reconciliation (summary/detail mismatches, wrong counts, stale cross-references, terminology drift) and additions mechanically implied by other content (missing steps, unstated thresholds, completeness gaps where the correct content is obvious). Must include suggested_fix.",
-      "present": "Requires individual user judgment -- strategic questions, design tradeoffs, or findings where reasonable people could disagree on the right action."
-    },
-    "finding_types": {
-      "error": "Something the document says that is wrong -- contradictions, incorrect statements, design tensions, incoherent tradeoffs. These are mistakes in what exists.",
-      "omission": "Something the document forgot to say -- missing mechanical steps, absent list entries, undefined thresholds, forgotten cross-references. These are gaps in completeness."
-    }
   }
 }

package/skills/document-review/references/subagent-template.md

@@ -19,20 +19,25 @@ Return ONLY valid JSON matching the findings schema below. No prose, no markdown
 {schema}
 
 Rules:
+- You are a leaf reviewer inside an already-running systematic review workflow. Do not invoke systematic skills or agents unless this template explicitly instructs you to. Perform your analysis directly and return findings in the required output format only.
 - Suppress any finding below your stated confidence floor (see your Confidence calibration section).
 - Every finding MUST include at least one evidence item -- a direct quote from the document.
 - You are operationally read-only. Analyze the document and produce findings. Do not edit the document, create files, or make changes. You may use non-mutating tools (file reads, glob, grep, git log) to gather context about the codebase when evaluating feasibility or existing patterns.
 - Set `finding_type` for every finding:
   - `error`: Something the document says that is wrong -- contradictions, incorrect statements, design tensions, incoherent tradeoffs.
   - `omission`: Something the document forgot to say -- missing mechanical steps, absent list entries, undefined thresholds, forgotten cross-references.
-- Set `autofix_class` based on whether there is one clear correct fix, not on severity. A P1 finding can be `auto` if the fix is obvious:
-  - `auto`: One clear correct fix. Applied silently without asking. The test: is there only one reasonable way to resolve this? If yes, it is auto. Two categories:
-    - Internal reconciliation: one part of the document is authoritative over another -- reconcile toward the authority. Examples: summary/detail mismatches, wrong counts, missing list entries derivable from elsewhere, stale cross-references, terminology drift, prose/diagram contradictions where prose is authoritative.
-    - Implied additions: the correct content is mechanically obvious from the document's own context. Examples: adding a missing implementation step implied by other content, defining a threshold implied but never stated, completeness gaps where what to add is clear.
-    Always include `suggested_fix` for auto findings.
-    NOT auto (the gap is clear but more than one reasonable fix exists): choosing an implementation approach when the document states a need without constraining how (e.g., "support offline mode" could mean service workers, local-first database, or queue-and-sync -- there is no single obvious answer), changing scope or priority where the author may have weighed tradeoffs the reviewer can't see (e.g., promoting a P2 to P1, or cutting a feature the document intentionally keeps at a lower tier).
-  - `present`: Requires judgment -- strategic questions, tradeoffs, design tensions where reasonable people could disagree, findings where the right action is unclear.
-- `suggested_fix` is required for `auto` findings. For `present` findings, `suggested_fix` is optional -- include it only when the fix is obvious, and frame as a question when the right action is unclear.
+- Set `autofix_class` based on whether there is one clear correct fix, not on severity or importance:
+  - `auto`: One clear correct fix, applied silently. This includes trivial fixes AND substantive ones:
+    - Internal reconciliation -- one document part authoritative over another (summary/detail mismatches, wrong counts, stale cross-references, terminology drift)
+    - Implied additions -- correct content mechanically obvious from the document (missing steps, unstated thresholds, completeness gaps)
+    - Codebase-pattern-resolved -- an established codebase pattern resolves ambiguity (cite the specific file/function in `why_it_matters`)
+    - Incorrect behavior -- the document describes behavior that is factually wrong, and the correct behavior is obvious from context or the codebase
+    - Missing standard security measures -- HTTPS enforcement, checksum verification, input sanitization, private IP rejection, or other controls with known implementations where omission is clearly a bug
+    - Incomplete technical descriptions -- the accurate/complete version is directly derivable from the codebase
+    - Missing requirements that follow mechanically from the document's own explicit, concrete decisions (not high-level goals -- a goal can be satisfied by multiple valid requirements)
+    The test is not "is this fix important?" but "is there more than one reasonable way to fix this?" If a competent implementer would arrive at the same fix independently, it is auto -- even if the fix is substantive. Always include `suggested_fix`. NOT auto if more than one reasonable fix exists or if scope/priority judgment is involved.
+  - `present`: Requires user judgment -- genuinely multiple valid approaches where the right choice depends on priorities, tradeoffs, or context the reviewer does not have. Examples: architectural choices with real tradeoffs, scope decisions, feature prioritization, UX design choices.
+- `suggested_fix` is required for `auto` findings. For `present` findings, include only when the fix is obvious.
 - If you find no issues, return an empty findings array. Still populate residual_risks and deferred_questions if applicable.
 - Use your suppress conditions. Do not flag issues that belong to other personas.
 </output-contract>
@@ -45,13 +50,3 @@ Document content:
 {document_content}
 </review-context>
 ```
-
-## Variable Reference
-
-| Variable | Source | Description |
-|----------|--------|-------------|
-| `{persona_file}` | Agent markdown file content | The full persona definition (identity, analysis protocol, calibration, suppress conditions) |
-| `{schema}` | `references/findings-schema.json` content | The JSON schema reviewers must conform to |
-| `{document_type}` | Orchestrator classification | Either "requirements" or "plan" |
-| `{document_path}` | Skill input | Path to the document being reviewed |
-| `{document_content}` | File read | The full document text |

package/skills/dspy-ruby/SKILL.md

@@ -647,14 +647,14 @@ end
 
 ## Resources
 
-- [core-concepts.md](./references/core-concepts.md) — Signatures, modules, predictors, type system deep-dive
-- [toolsets.md](./references/toolsets.md) — Tools::Base, Tools::Toolset DSL, type safety, testing
-- [providers.md](./references/providers.md) — Provider adapters, RubyLLM, fiber-local LM context, compatibility matrix
-- [optimization.md](./references/optimization.md) — MIPROv2, GEPA, evaluation framework, storage system
-- [observability.md](./references/observability.md) — Event system, dspy-o11y gems, Langfuse, score reporting
-- [signature-template.rb](./assets/signature-template.rb) — Signature scaffold with T::Enum, Date/Time, defaults, union types
-- [module-template.rb](./assets/module-template.rb) — Module scaffold with .call(), lifecycle callbacks, fiber-local LM
-- [config-template.rb](./assets/config-template.rb) — Rails initializer with RubyLLM, observability, feature flags
+- `references/core-concepts.md` — Signatures, modules, predictors, type system deep-dive
+- `references/toolsets.md` — Tools::Base, Tools::Toolset DSL, type safety, testing
+- `references/providers.md` — Provider adapters, RubyLLM, fiber-local LM context, compatibility matrix
+- `references/optimization.md` — MIPROv2, GEPA, evaluation framework, storage system
+- `references/observability.md` — Event system, dspy-o11y gems, Langfuse, score reporting
+- `assets/signature-template.rb` — Signature scaffold with T::Enum, Date/Time, defaults, union types
+- `assets/module-template.rb` — Module scaffold with .call(), lifecycle callbacks, fiber-local LM
+- `assets/config-template.rb` — Rails initializer with RubyLLM, observability, feature flags
 
 ## Key URLs
 

package/skills/every-style-editor/SKILL.md

@@ -44,7 +44,7 @@ Review each paragraph systematically, checking for:
 - Word choice and usage (overused words, passive voice)
 - Adherence to Every style guide rules
 
-Reference the complete [EVERY_WRITE_STYLE.md](./references/EVERY_WRITE_STYLE.md) for specific rules when in doubt.
+Reference the complete style guide at `references/EVERY_WRITE_STYLE.md` for specific rules when in doubt.
 
 ### Step 3: Mechanical Review
 
@@ -99,7 +99,7 @@ FINAL RECOMMENDATIONS
 
 ## Style Guide Reference
 
-The complete Every style guide is included in [EVERY_WRITE_STYLE.md](./references/EVERY_WRITE_STYLE.md). Key areas to focus on:
+The complete Every style guide is at `references/EVERY_WRITE_STYLE.md`. Key areas to focus on:
 
 - **Quick Rules**: Title case for headlines, sentence case elsewhere
 - **Tone**: Active voice, avoid overused words (actually, very, just), be specific
@@ -132,3 +132,4 @@ Based on Every's style guide, pay special attention to:
 - Word usage (fewer vs. less, they vs. them)
 - Company references (singular "it", teams as plural "they")
 - Job title capitalization
+

package/skills/frontend-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontend-design
-description: Build web interfaces with genuine design quality, not AI slop. Use for any frontend work - landing pages, web apps, dashboards, admin panels, components, interactive experiences. Activates for both greenfield builds and modifications to existing applications. Detects existing design systems and respects them. Covers composition, typography, color, motion, and copy. Verifies results via screenshots before declaring done.
+description: 'Build web interfaces with genuine design quality, not AI slop. Use for any frontend work - landing pages, web apps, dashboards, admin panels, components, interactive experiences. Activates for both greenfield builds and modifications to existing applications. Detects existing design systems and respects them. Covers composition, typography, color, motion, and copy. Verifies results via screenshots before declaring done.'
 ---
 
 # Frontend Design
@@ -230,7 +230,7 @@ Use the first available option:
 
 1. **Existing project browser tooling** -- if Playwright, Puppeteer, Cypress, or similar is already in the project's dependencies, use it. Do not introduce new dependencies just for verification.
 2. **Browser MCP tools** -- if browser automation tools (e.g., claude-in-chrome) are available in the agent's environment, use them.
-3. **agent-browser CLI** -- if nothing else is available, this is the default. Load the `agent-browser` skill for installation and usage instructions.
+3. **agent-browser CLI** -- if nothing else is available and `agent-browser` is installed, use it. If not installed, inform the user: "`agent-browser` is not installed. Run `/ce-setup` to install required dependencies." Then skip to the next option.
 4. **Mental review** -- if no browser access is possible (headless CI, no permissions to install), apply the litmus checks as a self-review and note that visual verification was skipped.
 
 ### What to Assess
@@ -256,4 +256,3 @@ For greenfield work, commit to a bold aesthetic direction. Consider the tone: br
 Ask: what makes this unforgettable? What is the one thing someone will remember?
 
 Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well, not from intensity.
-

package/skills/git-commit/SKILL.md

@@ -65,7 +65,7 @@ If the current branch from the context above is empty, the repository is in deta
 
 Follow this priority order:
 
-1. **Repo conventions already in context** -- If project instructions (AGENTS.md, AGENTS.md, or similar) are already loaded and specify commit message conventions, follow those. Do not re-read these files; they are loaded at session start.
+1. **Repo conventions already in context** -- If project instructions (AGENTS.md, or similar) are already loaded and specify commit message conventions, follow those. Do not re-read these files; they are loaded at session start.
 2. **Recent commit history** -- If no explicit convention is documented, examine the 10 most recent commits from Step 1. If a clear pattern emerges (e.g., conventional commits, ticket prefixes, emoji prefixes), match that pattern.
 3. **Default: conventional commits** -- If neither source provides a pattern, use conventional commit format: `type(scope): description` where type is one of `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`, `ci`, `style`, `build`.