@fro.bot/systematic 2.33.2 → 3.0.0

package/skills/slfg/SKILL.md

@@ -32,9 +32,8 @@ Wait for both to complete before continuing.
 
 ## Finalize Phase
 
-8. `/systematic:todo-resolve` — resolve findings, compound on learnings, clean up completed todos
-9. `/systematic:feature-video` — record the final walkthrough and add to PR
-10. Output `<promise>DONE</promise>` when video is in PR
+8. `/systematic:todos` (resolve) — resolve findings, compound on learnings, clean up completed todos
+9. Output `<promise>DONE</promise>` when work is complete
 
 Start with step 1 now.
 

package/skills/test-browser/SKILL.md

@@ -221,12 +221,12 @@ When a test fails:
 
    How to proceed?
    1. Fix now - I'll help debug and fix
-   2. Create todo - Add a todo for later (using the todo-create skill)
+   2. Create todo - Add a todo for later (using the todos skill, Create section)
    3. Skip - Continue testing other pages
    ```
 
 3. **If "Fix now":** investigate, propose a fix, apply, re-run the failing test
-4. **If "Create todo":** load the `todo-create` skill and create a todo with priority p1 and description `browser-test-{description}`, continue
+4. **If "Create todo":** load the `todos` skill (Create section) and create a todo with priority p1 and description `browser-test-{description}`, continue
 5. **If "Skip":** log as skipped, continue
 
 ### 10. Test Summary

package/skills/todos/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: todos
+description: Use when creating durable work items, managing todo lifecycle, or tracking findings across sessions in the file-based todo system; when reviewing pending todos for approval, prioritizing code review findings, or interactively categorizing work items; or when batch-resolving approved todos, especially after code review or triage sessions
+argument-hint: "[create|triage|resolve] [optional: findings list, source type, or specific todo ID/pattern]"
+disable-model-invocation: true
+---
+
+# File-Based Todo Tracking
+
+## Overview
+
+The `.context/systematic/todos/` directory is a file-based tracking system for code review feedback, technical debt, feature requests, and work items. Each todo is a markdown file with YAML frontmatter. This skill covers the full lifecycle in three sections: **Create** (new todos), **Triage** (review pending todos for approval), and **Resolve** (batch-implement approved todos).
+
+> **Legacy support:** Always check both `.context/systematic/todos/` (canonical) and `todos/` (legacy) when reading. Write new todos only to the canonical path. This directory has a multi-session lifecycle -- do not clean it up as scratch.
+
+## Directory Paths
+
+| Purpose | Path |
+|---------|------|
+| **Canonical (write here)** | `.context/systematic/todos/` |
+| **Legacy (read-only)** | `todos/` |
+
+## File Naming Convention
+
+```
+{issue_id}-{status}-{priority}-{description}.md
+```
+
+- **issue_id**: Sequential number (001, 002, ...) -- never reused
+- **status**: `pending` | `ready` | `complete`
+- **priority**: `p1` (critical) | `p2` (important) | `p3` (nice-to-have)
+- **description**: kebab-case, brief
+
+**Example:** `002-ready-p1-fix-n-plus-1.md`
+
+## File Structure
+
+Each todo has YAML frontmatter and structured sections. Use the todo template included below when creating new todos.
+
+```yaml
+---
+status: ready
+priority: p1
+issue_id: "002"
+tags: [rails, performance]
+dependencies: ["001"]     # Issue IDs this is blocked by
+---
+```
+
+**Required sections:** Problem Statement, Findings, Proposed Solutions, Recommended Action (filled during triage), Acceptance Criteria, Work Log.
+
+**Optional sections:** Technical Details, Resources, Notes.
+
+## Integration with Workflows
+
+| Trigger | Flow |
+|---------|------|
+| Code review | `/ce:review` -> Findings -> `/systematic:todos` (Triage section) -> Todos |
+| Autonomous review | `/ce:review mode:autofix` -> Residual todos -> `/systematic:todos` (Resolve section) |
+| Code TODOs | `/systematic:todos` (Resolve section) -> Fixes + Complex todos |
+| Planning | Brainstorm -> Create todo -> Work -> Complete |
+
+## Key Distinction
+
+This skill manages **durable, cross-session work items** persisted as markdown files. For temporary in-session step tracking, use platform task tools (`todowrite`/`TaskUpdate` in OpenCode, `update_plan` in Codex) instead.
+
+> **Tool preference:** Use native file-search/glob and content-search tools instead of shell commands for finding and reading todo files. Shell only for operations with no native equivalent (`mv`, `mkdir -p`).
+
+---
+
+## Create
+
+### Creating a New Todo
+
+1. `mkdir -p .context/systematic/todos/`
+2. Search both paths for `[0-9]*-*.md`, find the highest numeric prefix, increment, zero-pad to 3 digits.
+3. Use the todo template included below, write to canonical path as `{NEXT_ID}-pending-{priority}-{description}.md`.
+4. Fill Problem Statement, Findings, Proposed Solutions, Acceptance Criteria, and initial Work Log entry.
+5. Set status: `pending` (needs triage) or `ready` (pre-approved).
+
+**Create a todo when** the work needs more than ~15 minutes, has dependencies, requires planning, or needs prioritization. **Act immediately instead** when the fix is trivial, obvious, and self-contained.
+
+### Triaging Pending Items
+
+1. Glob `*-pending-*.md` in both paths.
+2. Review each todo's Problem Statement, Findings, and Proposed Solutions.
+3. Approve: rename `pending` -> `ready` in filename and frontmatter, fill Recommended Action.
+4. Defer: leave as `pending`.
+
+See the Triage section below for an interactive approval workflow.
+
+### Managing Dependencies
+
+```yaml
+dependencies: ["002", "005"]  # Blocked by these issues
+dependencies: []               # No blockers
+```
+
+To check blockers: search for `{dep_id}-complete-*.md` in both paths. Missing matches = incomplete blockers.
+
+### Completing a Todo
+
+1. Verify all acceptance criteria.
+2. Update Work Log with final session.
+3. Rename `ready` -> `complete` in filename and frontmatter.
+4. Check for unblocked work: search for files containing `dependencies:.*"{issue_id}"`.
+
+### Todo Template
+
+@./assets/todo-template.md
+
+---
+
+## Triage
+
+Interactive workflow for reviewing pending todos one by one and deciding whether to approve, skip, or modify each.
+
+**Do not write code during triage.** This is purely for review and prioritization -- implementation happens in the Resolve section below.
+
+- First set the /model to Haiku
+- Read all pending todos from `.context/systematic/todos/` and legacy `todos/` directories
+
+### 1. Present Each Finding
+
+For each pending todo, present it clearly with severity, category, description, location, problem scenario, proposed solution, and effort estimate. Then ask:
+
+```
+Do you want to add this to the todo list?
+1. yes - approve and mark ready
+2. next - skip (deletes the todo file)
+3. custom - modify before approving
+```
+
+Use severity levels: 🔴 P1 (CRITICAL), 🟡 P2 (IMPORTANT), 🔵 P3 (NICE-TO-HAVE).
+
+Include progress tracking in each header: `Progress: 3/10 completed`
+
+### 2. Handle Decision
+
+**yes:** Rename file from `pending` -> `ready` in both filename and frontmatter. Fill the Recommended Action section. If creating a new todo (not updating existing), use the naming convention from the Create section above.
+
+Priority mapping: 🔴 P1 -> `p1`, 🟡 P2 -> `p2`, 🔵 P3 -> `p3`
+
+Confirm: "✅ Approved: `{filename}` (Issue #{issue_id}) - Status: **ready**"
+
+**next:** Delete the todo file. Log as skipped for the final summary.
+
+**custom:** Ask what to modify, update, re-present, ask again.
+
+### 3. Final Summary
+
+After all items processed:
+
+```markdown
+## Triage Complete
+
+**Total Items:** [X] | **Approved (ready):** [Y] | **Skipped:** [Z]
+
+### Approved Todos (Ready for Work):
+- `042-ready-p1-transaction-boundaries.md` - Transaction boundary issue
+
+### Skipped (Deleted):
+- Item #5: [reason]
+```
+
+### 4. Next Steps
+
+```markdown
+What would you like to do next?
+
+1. proceed to the Resolve section below to resolve the todos
+2. commit the todos
+3. nothing, go chill
+```
+
+---
+
+## Resolve
+
+Resolve approved todos using parallel processing, document lessons learned, then clean up.
+
+Only `ready` todos are resolved. `pending` todos are skipped — they haven't been triaged yet. If pending todos exist, list them at the end so the user knows what was left behind.
+
+### 1. Analyze
+
+Scan `.context/systematic/todos/*.md` and legacy `todos/*.md`. Partition by status:
+
+- **`ready`** (status field or `-ready-` in filename): resolve these.
+- **`pending`**: skip. Report them at the end.
+- **`complete`**: ignore, already done.
+
+If a specific todo ID or pattern was passed as an argument, filter to matching todos only (still must be `ready`).
+
+Residual actionable work from `ce:review mode:autofix` after its `safe_auto` pass will already be `ready`.
+
+Skip any todo that recommends deleting, removing, or gitignoring files in `docs/brainstorms/`, `docs/plans/`, or `docs/solutions/` — these are intentional pipeline artifacts.
+
+### 2. Plan
+
+Create a task list grouped by type (e.g., `todowrite` in OpenCode, `update_plan` in Codex). Analyze dependencies -- items that others depend on run first. Output a mermaid diagram showing execution order and parallelism.
+
+### 3. Implement (PARALLEL)
+
+Spawn a `systematic:workflow:pr-comment-resolver` agent per item. Prefer parallel; fall back to sequential respecting dependency order.
+
+**Batching:** 1-4 items: direct parallel returns. 5+ items: batches of 4, each returning only a short status summary (todo handled, files changed, tests run/skipped, blockers).
+
+For large sets, use a scratch directory at `.context/systematic/todo-resolve/<run-id>/` for per-resolver artifacts. Return only completion summaries to parent.
+
+### 4. Commit & Resolve
+
+Commit changes, mark todos resolved, push to remote.
+
+GATE: STOP. Verify todos resolved and changes committed before proceeding.
+
+### 5. Compound on Lessons Learned
+
+Load the `ce:compound` skill to document what was learned. Todo resolutions often surface patterns and architectural insights worth capturing.
+
+GATE: STOP. Verify the compound skill produced a solution document in `docs/solutions/`. If none (user declined or no learnings), continue.
+
+### 6. Clean Up
+
+Delete completed/resolved todo files from both paths. If a scratch directory was created at `.context/systematic/todo-resolve/<run-id>/`, delete it (unless user asked to inspect).
+
+```
+Todos resolved: [count]
+Pending (skipped): [count, or "none"]
+Lessons documented: [path to solution doc, or "skipped"]
+Todos cleaned up: [count deleted]
+```
+
+If pending todos were skipped, list them:
+
+```
+Skipped pending todos (proceed to the Triage section above to approve):
+  - 003-pending-p2-missing-index.md
+  - 005-pending-p3-rename-variable.md
+```

package/skills/writing-skills/SKILL.md

@@ -596,7 +596,7 @@ Deploying untested skills = deploying untested code. It's a violation of quality
 
 ## Skill Creation Checklist (TDD Adapted)
 
-**IMPORTANT: Use TodoWrite to create todos for EACH checklist item below.**
+**IMPORTANT: Use todowrite to create todos for EACH checklist item below.**
 
 **RED Phase - Write Failing Test:**
 - [ ] Create pressure scenarios (3+ combined pressures for discipline skills)
@@ -645,6 +645,107 @@ How future Claude finds your skill:
 
 **Optimize for this flow** - put searchable terms early and often.
 
+## Systematic Bundled Skills
+
+Skills that live under this repo's `skills/` directory follow this skill's authoring discipline (pressure scenarios, trigger-oriented descriptions, concise bodies, references only when depth earns its keep) plus a Systematic-specific delta covering runtime frontmatter contracts, file layout, and identity defaults. This section is that delta.
+
+### When To Use
+
+Use this section when you are:
+
+- Creating a new bundled skill under `skills/`
+- Editing an existing bundled skill's frontmatter or file layout
+- Fixing content-integrity frontmatter or sub-file failures
+- Deciding whether a skill needs references, scripts, assets, or templates
+- Auditing bundled skills for provider-portable defaults
+
+For worked examples and judgment calls, read `references/foundation-conventions.md`.
+
+### Frontmatter Rules
+
+Every bundled skill must have YAML frontmatter with:
+
+- `name` - unprefixed skill identifier. The loader adds the `systematic:` command prefix automatically unless the skill intentionally belongs to another namespace such as `ce:`.
+- `description` - third-person trigger conditions. Prefer `Use when...`; describe when to load the skill, not its internal workflow.
+
+Optional fields are allowed only when the runtime loader recognizes them:
+
+| Field | Use |
+|---|---|
+| `argument-hint` | Shows expected invocation arguments. |
+| `disable-model-invocation` | Prevents direct model invocation for dispatcher-style skills. |
+| `allowed-tools` | Declares tool constraints for skill execution. |
+| `license` | Carries skill licensing metadata. |
+| `compatibility` | Notes platform or version compatibility. |
+| `metadata` | String-only metadata map. |
+| `user-invocable` | Marks whether users should invoke the skill directly. |
+| `agent` | Selects a companion agent when the loader supports it. |
+| `model` | Selects a model for skill execution when justified. |
+| `context` | Use `fork` when the skill should run in forked subtask context. |
+| `subtask` | Explicit forked-subtask marker recognized by the runtime. |
+
+`preconditions` is banned. It has no runtime consumer. Put prerequisite guidance in the skill body instead.
+
+### File Layout
+
+The required entry point is:
+
+```text
+skills/<skill-name>/SKILL.md
+```
+
+Optional sub-files must live under one of these directories:
+
+- `references/` - deeper guidance, decision tables, long examples, or API notes
+- `scripts/` - executable helpers an agent can run
+- `assets/` - static files used by the skill
+- `templates/` - reusable stubs or document templates
+
+Keep the main `SKILL.md` small enough to decide whether and how to proceed. Move heavy detail to `references/`, and cite it with a repo-local path such as `references/foundation-conventions.md` so the sub-file integrity gate can verify it exists.
+
+### Identity Defaults
+
+Bundled agents must omit the `model` field entirely:
+
+```yaml
+---
+name: example-agent
+description: ...
+# no `model:` line
+---
+```
+
+Per [OpenCode's agent docs](https://opencode.ai/docs/agents/), subagents with no `model` inherit the model of the primary agent that invoked them — which is the desired portable behavior. Do **not** declare `model: inherit`: that literal value is undocumented and produces `ProviderModelNotFoundError` on OpenCode older than ~v1.13.x (pre [sst/opencode#17888](https://github.com/sst/opencode/pull/17888)). Hardcoded provider model IDs (`anthropic/...`, `openai/...`, etc.) are also banned from **bundled agent markdown/frontmatter** because they break users on other providers. Source-owned category model defaults in TypeScript code are a separate mechanism — they are audited, centrally maintained, and do not violate this markdown rule.
+
+For agent or API attribution, `ai:systematic` is the machine ID used by Systematic-owned operations, such as a `by` field or `X-Agent-Id` header. It is not a skill cross-reference convention.
+
+### Validator
+
+Run the content-integrity gate before shipping skill changes:
+
+```bash
+bun 'scripts/content-integrity.ts'
+```
+
+The gate checks:
+
+- Skill frontmatter is present and uses only runtime-recognized fields.
+- Required `name` and `description` fields are non-empty.
+- Banned frontmatter such as `preconditions` is absent.
+- Bundled agents omit the `model` field.
+- Skill references to `references/`, `scripts/`, `assets/`, and `templates/` resolve on disk.
+
+If the gate fails, fix the content rather than broadening the validator unless the runtime loader contract has actually changed.
+
+### Common Mistakes (Systematic Bundled Skills)
+
+| Mistake | Fix |
+|---|---|
+| Adding a new frontmatter field because it reads well | Add body prose instead, unless the runtime loader consumes the field. |
+| Summarizing the whole workflow in `description` | Describe trigger conditions only. |
+| Adding any `model` field to a bundled agent | Omit the field; subagents inherit from the invoking primary agent. |
+| Linking to a non-existent reference file | Create the file or remove the link. |
+
 ## The Bottom Line
 
 **Creating skills IS TDD for process documentation.**

package/skills/{writing-systematic-skills → writing-skills}/references/foundation-conventions.md

@@ -1,6 +1,6 @@
 # Foundation Conventions
 
-This reference expands the Systematic-specific rules from `SKILL.md`. The mechanical rules are enforced by `bun scripts/content-integrity.ts`; this file explains the judgment calls behind them.
+This reference expands the Systematic-specific rules from the "Systematic Bundled Skills" section of `SKILL.md`. The mechanical rules are enforced by `bun scripts/content-integrity.ts`; this file explains the judgment calls behind them.
 
 ## Frontmatter
 
@@ -8,8 +8,8 @@ Systematic skill frontmatter mirrors what the runtime loader actually reads. Do
 
 | Field | Required | When To Use | Enforcement | Example |
 |---|---:|---|---|---|
-| `name` | Yes | Every skill. Use the unprefixed skill identifier unless another namespace is intentional. | Read + enforced (loader rejects missing/null) | `name: writing-systematic-skills` |
-| `description` | Yes | Trigger-oriented discovery text. Third person. Prefer `Use when...`. | Read + enforced (loader rejects missing/null) | `description: Use when fixing bundled skill frontmatter failures...` |
+| `name` | Yes | Every skill. Use the unprefixed skill identifier unless another namespace is intentional. | Read + enforced (loader rejects missing/null) | `name: writing-skills` |
+| `description` | Yes | Trigger-oriented discovery text. Third person. Prefer `Use when...`. | Read + enforced (loader rejects missing/null) | `description: Use when creating new skills, editing existing skills, or verifying skills work before deployment` |
 | `argument-hint` | No | The skill accepts meaningful invocation arguments. | Read + surfaced to callers | `argument-hint: "[path/to/document.md]"` |
 | `disable-model-invocation` | No | Dispatcher or routing skills that should not be directly model-invoked. | Read + enforced (loader acts on it) | `disable-model-invocation: true` |
 | `allowed-tools` | No | The skill needs an explicit tool allowlist. | **Read but not enforced.** `src/lib/skills.ts` parses it into `SkillFrontmatter.allowedTools` and passes it through, but no permission gate in `src/lib` acts on it. OpenCode treats it as metadata, not enforced permissions. Do not rely on this field to restrict tool access. | `allowed-tools: Bash, Read` |
@@ -126,9 +126,9 @@ Systematic provides source-owned category model defaults in TypeScript code for
 
 ### Machine ID
 
-`ai:systematic` is a machine identity string for Systematic-owned operations. Proof uses it as the `by` field on operations and the `X-Agent-Id` header. Keep it lowercase and stable.
+`ai:systematic` is a machine identity string for Systematic-owned operations, used as the `by` field on operations and the `X-Agent-Id` header where applicable. Keep it lowercase and stable.
 
-Do not use `ai:systematic` as a skill-reference pattern. Skill and agent references use their own namespaces, such as `systematic:writing-systematic-skills` or `systematic:research:best-practices-researcher`.
+Do not use `ai:systematic` as a skill-reference pattern. Skill and agent references use their own namespaces, such as `systematic:writing-skills` or `systematic:research:best-practices-researcher`.
 
 ### Public-Facing Voice
 

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

@@ -1,95 +0,0 @@
----
-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
-temperature: 0.1
----
-
-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.
-
-Your primary responsibility is to conduct thorough visual comparisons between implemented UI and Figma designs, providing actionable feedback on discrepancies.
-
-## Your Workflow
-
-1. **Capture Implementation State**
-   - Use agent-browser CLI to capture screenshots of the implemented UI
-   - Test different viewport sizes if the design includes responsive breakpoints
-   - Capture interactive states (hover, focus, active) when relevant
-   - Document the URL and selectors of the components being reviewed
-
-   ```bash
-   agent-browser open [url]
-   agent-browser snapshot -i
-   agent-browser screenshot output.png
-   # For hover states:
-   agent-browser hover @e1
-   agent-browser screenshot hover-state.png
-   ```
-
-2. **Retrieve Design Specifications**
-   - Use the Figma MCP to access the corresponding design files
-   - Extract design tokens (colors, typography, spacing, shadows)
-   - Identify component specifications and design system rules
-   - Note any design annotations or developer handoff notes
-
-3. **Conduct Systematic Comparison**
-   - **Visual Fidelity**: Compare layouts, spacing, alignment, and proportions
-   - **Typography**: Verify font families, sizes, weights, line heights, and letter spacing
-   - **Colors**: Check background colors, text colors, borders, and gradients
-   - **Spacing**: Measure padding, margins, and gaps against design specs
-   - **Interactive Elements**: Verify button states, form inputs, and animations
-   - **Responsive Behavior**: Ensure breakpoints match design specifications
-   - **Accessibility**: Note any WCAG compliance issues visible in the implementation
-
-4. **Generate Structured Review**
-   Structure your review as follows:
-   ```
-   ## Design Implementation Review
-   
-   ### ✅ Correctly Implemented
-   - [List elements that match the design perfectly]
-   
-   ### ⚠️ Minor Discrepancies
-   - [Issue]: [Current implementation] vs [Expected from Figma]
-     - Impact: [Low/Medium]
-     - Fix: [Specific CSS/code change needed]
-   
-   ### ❌ Major Issues
-   - [Issue]: [Description of significant deviation]
-     - Impact: High
-     - Fix: [Detailed correction steps]
-   
-   ### 📐 Measurements
-   - [Component]: Figma: [value] | Implementation: [value]
-   
-   ### 💡 Recommendations
-   - [Suggestions for improving design consistency]
-   ```
-
-5. **Provide Actionable Fixes**
-   - Include specific CSS properties and values that need adjustment
-   - Reference design tokens from the design system when applicable
-   - Suggest code snippets for complex fixes
-   - Prioritize fixes based on visual impact and user experience
-
-## Important Guidelines
-
-- **Be Precise**: Use exact pixel values, hex codes, and specific CSS properties
-- **Consider Context**: Some variations might be intentional (e.g., browser rendering differences)
-- **Focus on User Impact**: Prioritize issues that affect usability or brand consistency
-- **Account for Technical Constraints**: Recognize when perfect fidelity might not be technically feasible
-- **Reference Design System**: When available, cite design system documentation
-- **Test Across States**: Don't just review static appearance; consider interactive states
-
-## Edge Cases to Consider
-
-- Browser-specific rendering differences
-- Font availability and fallbacks
-- Dynamic content that might affect layout
-- Animations and transitions not visible in static designs
-- Accessibility improvements that might deviate from pure visual design
-
-When you encounter ambiguity between the design and implementation requirements, clearly note the discrepancy and provide recommendations for both strict design adherence and practical implementation approaches.
-
-Your goal is to ensure the implementation delivers the intended user experience while maintaining design consistency and technical excellence.
-