@fro.bot/systematic 2.2.0 → 2.3.0

package/skills/ce-review-beta/references/persona-catalog.md

@@ -1,50 +0,0 @@
-# Persona Catalog
-
-8 reviewer personas organized in two tiers, plus CE-specific agents. The orchestrator uses this catalog to select which reviewers to spawn for each review.
-
-## Always-on (3 personas + 2 CE agents)
-
-Spawned on every review regardless of diff content.
-
-**Persona agents (structured JSON output):**
-
-| Persona | Agent | Focus |
-|---------|-------|-------|
-| `correctness` | `systematic:review:correctness-reviewer` | Logic errors, edge cases, state bugs, error propagation, intent compliance |
-| `testing` | `systematic:review:testing-reviewer` | Coverage gaps, weak assertions, brittle tests, missing edge case tests |
-| `maintainability` | `systematic:review:maintainability-reviewer` | Coupling, complexity, naming, dead code, premature abstraction |
-
-**CE agents (unstructured output, synthesized separately):**
-
-| Agent | Focus |
-|-------|-------|
-| `systematic:review:agent-native-reviewer` | Verify new features are agent-accessible |
-| `systematic:research:learnings-researcher` | Search docs/solutions/ for past issues related to this PR's modules and patterns |
-
-## Conditional (5 personas)
-
-Spawned when the orchestrator identifies relevant patterns in the diff. The orchestrator reads the full diff and reasons about selection -- this is agent judgment, not keyword matching.
-
-| Persona | Agent | Select when diff touches... |
-|---------|-------|---------------------------|
-| `security` | `systematic:review:security-reviewer` | Auth middleware, public endpoints, user input handling, permission checks, secrets management |
-| `performance` | `systematic:review:performance-reviewer` | Database queries, ORM calls, loop-heavy data transforms, caching layers, async/concurrent code |
-| `api-contract` | `systematic:review:api-contract-reviewer` | Route definitions, serializer/interface changes, event schemas, exported type signatures, API versioning |
-| `data-migrations` | `systematic:review:data-migrations-reviewer` | Migration files, schema changes, backfill scripts, data transformations |
-| `reliability` | `systematic:review:reliability-reviewer` | Error handling, retry logic, circuit breakers, timeouts, background jobs, async handlers, health checks |
-
-## CE Conditional Agents (migration-specific)
-
-These CE-native agents provide specialized analysis beyond what the persona agents cover. Spawn them when the diff includes database migrations, schema.rb, or data backfills.
-
-| Agent | Focus |
-|-------|-------|
-| `systematic:review:schema-drift-detector` | Cross-references schema.rb changes against included migrations to catch unrelated drift |
-| `systematic:review:deployment-verification-agent` | Produces Go/No-Go deployment checklist with SQL verification queries and rollback procedures |
-
-## Selection rules
-
-1. **Always spawn all 3 always-on personas** plus the 2 CE always-on agents.
-2. **For each conditional persona**, the orchestrator reads the diff and decides whether the persona's domain is relevant. This is a judgment call, not a keyword match.
-3. **For CE conditional agents**, spawn when the diff includes migration files (`db/migrate/*.rb`, `db/schema.rb`) or data backfill scripts.
-4. **Announce the team** before spawning with a one-line justification per conditional reviewer selected.

package/skills/ce-review-beta/references/subagent-template.md

@@ -1,56 +0,0 @@
-# Sub-agent Prompt Template
-
-This template is used by the orchestrator to spawn each reviewer sub-agent. Variable substitution slots are filled at spawn time.
-
----
-
-## Template
-
-```
-You are a specialist code reviewer.
-
-<persona>
-{persona_file}
-</persona>
-
-<scope-rules>
-{diff_scope_rules}
-</scope-rules>
-
-<output-contract>
-Return ONLY valid JSON matching the findings schema below. No prose, no markdown, no explanation outside the JSON object.
-
-{schema}
-
-Rules:
-- Suppress any finding below your stated confidence floor (see your Confidence calibration section).
-- Every finding MUST include at least one evidence item grounded in the actual code.
-- Set pre_existing to true ONLY for issues in unchanged code that are unrelated to this diff. If the diff makes the issue newly relevant, it is NOT pre-existing.
-- You are operationally read-only. You may use non-mutating inspection commands, including read-oriented `git` / `gh` commands, to gather evidence. Do not edit files, change branches, commit, push, create PRs, or otherwise mutate the checkout or repository state.
-- Set `autofix_class` conservatively. Use `safe_auto` only when the fix is local, deterministic, and low-risk. Use `gated_auto` when a concrete fix exists but changes behavior/contracts/permissions. Use `manual` for actionable residual work. Use `advisory` for report-only items that should not become code-fix work.
-- Set `owner` to the default next actor for this finding: `review-fixer`, `downstream-resolver`, `human`, or `release`.
-- Set `requires_verification` to true whenever the likely fix needs targeted tests, a focused re-review, or operational validation before it should be trusted.
-- suggested_fix is optional. Only include it when the fix is obvious and correct. A bad suggestion is worse than none.
-- If you find no issues, return an empty findings array. Still populate residual_risks and testing_gaps if applicable.
-</output-contract>
-
-<review-context>
-Intent: {intent_summary}
-
-Changed files: {file_list}
-
-Diff:
-{diff}
-</review-context>
-```
-
-## Variable Reference
-
-| Variable | Source | Description |
-|----------|--------|-------------|
-| `{persona_file}` | Agent markdown file content | The full persona definition (identity, failure modes, calibration, suppress conditions) |
-| `{diff_scope_rules}` | `references/diff-scope.md` content | Primary/secondary/pre-existing tier rules |
-| `{schema}` | `references/findings-schema.json` content | The JSON schema reviewers must conform to |
-| `{intent_summary}` | Stage 2 output | 2-3 line description of what the change is trying to accomplish |
-| `{file_list}` | Stage 1 output | List of changed files from the scope step |
-| `{diff}` | Stage 1 output | The actual diff content to review |

package/skills/file-todos/SKILL.md

@@ -1,231 +0,0 @@
----
-name: file-todos
-description: This skill should be used when managing the file-based todo tracking system in the .context/systematic/todos/ directory. It provides workflows for creating todos, managing status and dependencies, conducting triage, and integrating with code review processes.
-disable-model-invocation: true
----
-
-# File-Based Todo Tracking Skill
-
-## Overview
-
-The `.context/systematic/todos/` directory contains a file-based tracking system for managing code review feedback, technical debt, feature requests, and work items. Each todo is a markdown file with YAML frontmatter and structured sections.
-
-> **Legacy support:** During the transition period, always check both `.context/systematic/todos/` (canonical) and `todos/` (legacy) when reading or searching for todos. Write new todos only to the canonical path. Unlike per-run scratch directories, `.context/systematic/todos/` has a multi-session lifecycle -- do not clean it up as part of post-run scratch cleanup.
-
-This skill should be used when:
-- Creating new todos from findings or feedback
-- Managing todo lifecycle (pending -> ready -> complete)
-- Triaging pending items for approval
-- Checking or managing dependencies
-- Converting PR comments or code findings into tracked work
-- Updating work logs during todo execution
-
-## Directory Paths
-
-| Purpose | Path |
-|---------|------|
-| **Canonical (write here)** | `.context/systematic/todos/` |
-| **Legacy (read-only)** | `todos/` |
-
-When searching or listing todos, always search both paths. When creating new todos, always write to the canonical path.
-
-## File Naming Convention
-
-```
-{issue_id}-{status}-{priority}-{description}.md
-```
-
-**Components:**
-- **issue_id**: Sequential number (001, 002, 003...) -- never reused
-- **status**: `pending` (needs triage), `ready` (approved), `complete` (done)
-- **priority**: `p1` (critical), `p2` (important), `p3` (nice-to-have)
-- **description**: kebab-case, brief description
-
-**Examples:**
-```
-001-pending-p1-mailer-test.md
-002-ready-p1-fix-n-plus-1.md
-005-complete-p2-refactor-csv.md
-```
-
-## File Structure
-
-Each todo is a markdown file with YAML frontmatter and structured sections. Use the template at [todo-template.md](./assets/todo-template.md) as a starting point when creating new todos.
-
-**Required sections:**
-- **Problem Statement** -- What is broken, missing, or needs improvement?
-- **Findings** -- Investigation results, root cause, key discoveries
-- **Proposed Solutions** -- Multiple options with pros/cons, effort, risk
-- **Recommended Action** -- Clear plan (filled during triage)
-- **Acceptance Criteria** -- Testable checklist items
-- **Work Log** -- Chronological record with date, actions, learnings
-
-**Optional sections:**
-- **Technical Details** -- Affected files, related components, DB changes
-- **Resources** -- Links to errors, tests, PRs, documentation
-- **Notes** -- Additional context or decisions
-
-**YAML frontmatter fields:**
-```yaml
----
-status: ready              # pending | ready | complete
-priority: p1              # p1 | p2 | p3
-issue_id: "002"
-tags: [rails, performance, database]
-dependencies: ["001"]     # Issue IDs this is blocked by
----
-```
-
-## Common Workflows
-
-> **Tool preference:** Use native file-search (e.g., Glob in OpenCode) and content-search (e.g., Grep in OpenCode) tools instead of shell commands for finding and reading todo files. This avoids unnecessary permission prompts in sub-agent workflows. Use shell only for operations that have no native equivalent (e.g., `mv` for renames, `mkdir -p` for directory creation).
-
-### Creating a New Todo
-
-1. Ensure directory exists: `mkdir -p .context/systematic/todos/`
-2. Determine next issue ID by searching both canonical and legacy paths for files matching `[0-9]*-*.md` using the native file-search/glob tool. Extract the numeric prefix from each filename, find the highest, and increment by one. Zero-pad to 3 digits (e.g., `007`).
-3. Read the template at [todo-template.md](./assets/todo-template.md), then write it to `.context/systematic/todos/{NEXT_ID}-pending-{priority}-{description}.md` using the native file-write tool.
-4. Edit and fill required sections:
-   - Problem Statement
-   - Findings (if from investigation)
-   - Proposed Solutions (multiple options)
-   - Acceptance Criteria
-   - Add initial Work Log entry
-5. Determine status: `pending` (needs triage) or `ready` (pre-approved)
-6. Add relevant tags for filtering
-
-**When to create a todo:**
-- Requires more than 15-20 minutes of work
-- Needs research, planning, or multiple approaches considered
-- Has dependencies on other work
-- Requires manager approval or prioritization
-- Part of larger feature or refactor
-- Technical debt needing documentation
-
-**When to act immediately instead:**
-- Issue is trivial (< 15 minutes)
-- Complete context available now
-- No planning needed
-- User explicitly requests immediate action
-- Simple bug fix with obvious solution
-
-### Triaging Pending Items
-
-1. Find pending items using the native file-search/glob tool with pattern `*-pending-*.md` in both directory paths.
-2. For each todo:
-   - Read Problem Statement and Findings
-   - Review Proposed Solutions
-   - Make decision: approve, defer, or modify priority
-3. Update approved todos:
-   - Rename file: `mv {file}-pending-{pri}-{desc}.md {file}-ready-{pri}-{desc}.md`
-   - Update frontmatter: `status: pending` -> `status: ready`
-   - Fill "Recommended Action" section with clear plan
-   - Adjust priority if different from initial assessment
-4. Deferred todos stay in `pending` status
-
-Load the `triage` skill for an interactive approval workflow.
-
-### Managing Dependencies
-
-**To track dependencies:**
-
-```yaml
-dependencies: ["002", "005"]  # This todo blocked by issues 002 and 005
-dependencies: []               # No blockers - can work immediately
-```
-
-**To check what blocks a todo:** Use the native content-search tool (e.g., Grep in OpenCode) to search for `^dependencies:` in the todo file.
-
-**To find what a todo blocks:** Search both directory paths for files containing `dependencies:.*"002"` using the native content-search tool.
-
-**To verify blockers are complete before starting:** For each dependency ID, use the native file-search/glob tool to look for `{dep_id}-complete-*.md` in both directory paths. Any missing matches indicate incomplete blockers.
-
-### Updating Work Logs
-
-When working on a todo, always add a work log entry:
-
-```markdown
-### YYYY-MM-DD - Session Title
-
-**By:** Agent name / Developer Name
-
-**Actions:**
-- Specific changes made (include file:line references)
-- Commands executed
-- Tests run
-- Results of investigation
-
-**Learnings:**
-- What worked / what didn't
-- Patterns discovered
-- Key insights for future work
-```
-
-Work logs serve as:
-- Historical record of investigation
-- Documentation of approaches attempted
-- Knowledge sharing for team
-- Context for future similar work
-
-### Completing a Todo
-
-1. Verify all acceptance criteria checked off
-2. Update Work Log with final session and results
-3. Rename file: `mv {file}-ready-{pri}-{desc}.md {file}-complete-{pri}-{desc}.md`
-4. Update frontmatter: `status: ready` -> `status: complete`
-5. Check for unblocked work: search both directory paths for `*-ready-*.md` files containing `dependencies:.*"{issue_id}"` using the native content-search tool
-6. Commit with issue reference: `feat: resolve issue 002`
-
-## Integration with Development Workflows
-
-| Trigger | Flow | Tool |
-|---------|------|------|
-| Code review | `/ce:review` -> Findings -> `/triage` -> Todos | Review agent + skill |
-| Beta autonomous review | `/ce:review-beta mode:autonomous` -> Downstream-resolver residual todos -> `/resolve-todo-parallel` | Review skill + todos |
-| PR comments | `/resolve_pr_parallel` -> Individual fixes -> Todos | gh CLI + skill |
-| Code TODOs | `/resolve-todo-parallel` -> Fixes + Complex todos | Agent + skill |
-| Planning | Brainstorm -> Create todo -> Work -> Complete | Skill |
-| Feedback | Discussion -> Create todo -> Triage -> Work | Skill |
-
-## Quick Reference Patterns
-
-Use the native file-search/glob tool (e.g., Glob in OpenCode) and content-search tool (e.g., Grep in OpenCode) for these operations. Search both canonical and legacy directory paths.
-
-**Finding work:**
-
-| Goal | Tool | Pattern |
-|------|------|---------|
-| List highest priority unblocked work | Content-search | `dependencies: \[\]` in `*-ready-p1-*.md` |
-| List all pending items needing triage | File-search | `*-pending-*.md` |
-| Find next issue ID | File-search | `[0-9]*-*.md`, extract highest numeric prefix |
-| Count by status | File-search | `*-pending-*.md`, `*-ready-*.md`, `*-complete-*.md` |
-
-**Dependency management:**
-
-| Goal | Tool | Pattern |
-|------|------|---------|
-| What blocks this todo? | Content-search | `^dependencies:` in the specific todo file |
-| What does this todo block? | Content-search | `dependencies:.*"{id}"` across all todo files |
-
-**Searching:**
-
-| Goal | Tool | Pattern |
-|------|------|---------|
-| Search by tag | Content-search | `tags:.*{tag}` across all todo files |
-| Search by priority | File-search | `*-p1-*.md` (or p2, p3) |
-| Full-text search | Content-search | `{keyword}` across both directory paths |
-
-## Key Distinctions
-
-**File-todos system (this skill):**
-- Markdown files in `.context/systematic/todos/` (legacy: `todos/`)
-- Development/project tracking across sessions and agents
-- Standalone markdown files with YAML frontmatter
-- Persisted to disk, cross-agent accessible
-
-**In-session task tracking (e.g., todowrite/TaskUpdate in OpenCode, update_plan in Codex):**
-- In-memory task tracking during agent sessions
-- Temporary tracking for single conversation
-- Not persisted to disk after session ends
-- Different purpose: use for tracking steps within a session, not for durable cross-session work items
-

package/skills/resolve-pr-parallel/SKILL.md

@@ -1,96 +0,0 @@
----
-name: resolve-pr-parallel
-description: Resolve all PR comments using parallel processing. Use when addressing PR review feedback, resolving review threads, or batch-fixing PR comments.
-argument-hint: '[optional: PR number or current PR]'
-disable-model-invocation: true
-allowed-tools: Bash(gh *), Bash(git *), Read
----
-
-# Resolve PR Comments in Parallel
-
-Resolve all unresolved PR review comments by spawning parallel agents for each thread.
-
-## Context Detection
-
-Detect git context from the current working directory:
-- Current branch and associated PR
-- All PR comments and review threads
-- Works with any PR by specifying the number
-
-## Workflow
-
-### 1. Analyze
-
-Fetch unresolved review threads using the GraphQL script at [scripts/get-pr-comments](scripts/get-pr-comments):
-
-```bash
-bash scripts/get-pr-comments PR_NUMBER
-```
-
-This returns only **unresolved, non-outdated** threads with file paths, line numbers, and comment bodies.
-
-If the script fails, fall back to:
-```bash
-gh pr view PR_NUMBER --json reviews,comments
-gh api repos/{owner}/{repo}/pulls/PR_NUMBER/comments
-```
-
-### 2. Plan
-
-Create a task list of all unresolved items grouped by type (e.g., `todowrite` in OpenCode, `update_plan` in Codex):
-- Code changes requested
-- Questions to answer
-- Style/convention fixes
-- Test additions needed
-
-### 3. Implement (PARALLEL)
-
-Spawn a `systematic:workflow:pr-comment-resolver` agent for each unresolved item.
-
-If there are 3 comments, spawn 3 agents — one per comment. Prefer running all agents in parallel; if the platform does not support parallel dispatch, run them sequentially.
-
-Keep parent-context pressure bounded:
-- If there are 1-4 unresolved items, direct parallel returns are fine
-- If there are 5+ unresolved items, launch in batches of at most 4 agents at a time
-- Require each resolver agent to return a short status summary to the parent: comment/thread handled, files changed, tests run or skipped, any blocker that still needs human attention, and for question-only threads the substantive reply text so the parent can post or verify it
-
-If the PR is large enough that even batched short returns are likely to get noisy, use a per-run scratch directory such as `.context/systematic/resolve-pr-parallel/<run-id>/`:
-- Have each resolver write a compact artifact for its thread there
-- Return only a completion summary to the parent
-- Re-read only the artifacts that are needed to resolve threads, answer reviewer questions, or summarize the batch
-
-### 4. Commit & Resolve
-
-- Commit changes with a clear message referencing the PR feedback
-- Resolve each thread programmatically using [scripts/resolve-pr-thread](scripts/resolve-pr-thread):
-
-```bash
-bash scripts/resolve-pr-thread THREAD_ID
-```
-
-- Push to remote
-
-### 5. Verify
-
-Re-fetch comments to confirm all threads are resolved:
-
-```bash
-bash scripts/get-pr-comments PR_NUMBER
-```
-
-Should return an empty array `[]`. If threads remain, repeat from step 1.
-
-If a scratch directory was used and the user did not ask to inspect it, clean it up after verification succeeds.
-
-## Scripts
-
-- [scripts/get-pr-comments](scripts/get-pr-comments) - GraphQL query for unresolved review threads
-- [scripts/resolve-pr-thread](scripts/resolve-pr-thread) - GraphQL mutation to resolve a thread by ID
-
-## Success Criteria
-
-- All unresolved review threads addressed
-- Changes committed and pushed
-- Threads resolved via GraphQL (marked as resolved on GitHub)
-- Empty result from get-pr-comments on verify
-

package/skills/resolve-pr-parallel/scripts/get-pr-comments

@@ -1,68 +0,0 @@
-#!/usr/bin/env bash
-
-set -e
-
-if [ $# -lt 1 ]; then
-    echo "Usage: get-pr-comments PR_NUMBER [OWNER/REPO]"
-    echo "Example: get-pr-comments 123"
-    echo "Example: get-pr-comments 123 EveryInc/cora"
-    exit 1
-fi
-
-PR_NUMBER=$1
-
-if [ -n "$2" ]; then
-    OWNER=$(echo "$2" | cut -d/ -f1)
-    REPO=$(echo "$2" | cut -d/ -f2)
-else
-    OWNER=$(gh repo view --json owner -q .owner.login 2>/dev/null)
-    REPO=$(gh repo view --json name -q .name 2>/dev/null)
-fi
-
-if [ -z "$OWNER" ] || [ -z "$REPO" ]; then
-    echo "Error: Could not detect repository. Pass OWNER/REPO as second argument."
-    exit 1
-fi
-
-gh api graphql -f owner="$OWNER" -f repo="$REPO" -F pr="$PR_NUMBER" -f query='
-query FetchUnresolvedComments($owner: String!, $repo: String!, $pr: Int!) {
-  repository(owner: $owner, name: $repo) {
-    pullRequest(number: $pr) {
-      title
-      url
-      reviewThreads(first: 100) {
-        totalCount
-        edges {
-          node {
-            id
-            isResolved
-            isOutdated
-            isCollapsed
-            path
-            line
-            startLine
-            diffSide
-            comments(first: 100) {
-              totalCount
-              nodes {
-                id
-                author {
-                  login
-                }
-                body
-                createdAt
-                updatedAt
-                url
-                outdated
-              }
-            }
-          }
-        }
-        pageInfo {
-          hasNextPage
-          endCursor
-        }
-      }
-    }
-  }
-}' | jq '.data.repository.pullRequest.reviewThreads.edges | map(select(.node.isResolved == false and .node.isOutdated == false))'

package/skills/resolve-todo-parallel/SKILL.md

@@ -1,68 +0,0 @@
----
-name: resolve-todo-parallel
-description: Resolve all pending CLI todos using parallel processing, compound on lessons learned, then clean up completed todos.
-argument-hint: '[optional: specific todo ID or pattern]'
----
-
-Resolve all TODO comments using parallel processing, document lessons learned, then clean up completed todos.
-
-## Workflow
-
-### 1. Analyze
-
-Get all unresolved TODOs from `.context/systematic/todos/*.md` and legacy `todos/*.md`
-
-Residual actionable work may come from `ce:review-beta mode:autonomous` after its in-skill `safe_auto` pass. Treat those todos as normal unresolved work items; the review skill has already decided they should not be auto-fixed inline.
-
-If any todo recommends deleting, removing, or gitignoring files in `docs/brainstorms/`, `docs/plans/`, or `docs/solutions/`, skip it and mark it as `wont_fix`. These are systematic pipeline artifacts that are intentional and permanent.
-
-### 2. Plan
-
-Create a task list of all unresolved items grouped by type (e.g., `todowrite` in OpenCode, `update_plan` in Codex). Analyze dependencies and prioritize items that others depend on. For example, if a rename is needed, it must complete before dependent items. Output a mermaid flow diagram showing execution order — what can run in parallel, and what must run first.
-
-### 3. Implement (PARALLEL)
-
-Spawn a `systematic:workflow:pr-comment-resolver` agent for each unresolved item.
-
-If there are 3 items, spawn 3 agents — one per item. Prefer running all agents in parallel; if the platform does not support parallel dispatch, run them sequentially respecting the dependency order from step 2.
-
-Keep parent-context pressure bounded:
-- If there are 1-4 unresolved items, direct parallel returns are fine
-- If there are 5+ unresolved items, launch in batches of at most 4 agents at a time
-- Require each resolver agent to return only a short status summary to the parent: todo handled, files changed, tests run or skipped, and any blocker that still needs follow-up
-
-If the todo set is large enough that even batched short returns are likely to get noisy, use a per-run scratch directory such as `.context/systematic/resolve-todo-parallel/<run-id>/`:
-- Have each resolver write a compact artifact for its todo there
-- Return only a completion summary to the parent
-- Re-read only the artifacts that are needed to summarize outcomes, document learnings, or decide whether a todo is truly resolved
-
-### 4. Commit & Resolve
-
-- Commit changes
-- Remove the TODO from the file, and mark it as resolved.
-- Push to remote
-
-GATE: STOP. Verify that todos have been resolved and changes committed. Do NOT proceed to step 5 if no todos were resolved.
-
-### 5. Compound on Lessons Learned
-
-Load the `ce:compound` skill to document what was learned from resolving the todos.
-
-The todo resolutions often surface patterns, recurring issues, or architectural insights worth capturing. This step ensures that knowledge compounds rather than being lost.
-
-GATE: STOP. Verify that the compound skill produced a solution document in `docs/solutions/`. If no document was created (user declined or no non-trivial learnings), continue to step 6.
-
-### 6. Clean Up Completed Todos
-
-Search both `.context/systematic/todos/` and legacy `todos/` for files with `done`, `resolved`, or `complete` status, then delete them to keep the todo list clean and actionable.
-
-If a per-run scratch directory was created at `.context/systematic/resolve-todo-parallel/<run-id>/`, and the user did not ask to inspect it, delete that specific `<run-id>/` directory after todo cleanup succeeds. Do not delete any other `.context/` subdirectories.
-
-After cleanup, output a summary:
-
-```
-Todos resolved: [count]
-Lessons documented: [path to solution doc, or "skipped"]
-Todos cleaned up: [count deleted]
-```
-