agentforge-framework 0.2.0__py3-none-any.whl

agentforge_framework/skills/to-tickets/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: to-tickets
+description: Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker (edges as text in one file per ticket locally, or native blocking links on a real tracker).
+disable-model-invocation: true
+---
+
+# To Tickets
+
+Break a plan, spec, or conversation into a set of **tickets**: tracer-bullet vertical slices, each declaring the tickets that **block** it.
+
+The issue tracker and triage label vocabulary should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`.
+
+## Process
+
+### 1. Gather context
+
+Work from whatever is already in the conversation context. If the user passes a reference (a spec path, an issue number or URL) as an argument, fetch it and read its full body and comments.
+
+### 2. Explore the codebase (optional)
+
+If you have not already explored the codebase, do so to understand the current state of the code. Ticket titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching.
+
+Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change."
+
+### 3. Draft vertical slices
+
+Break the work into **tracer bullet** tickets.
+
+<vertical-slice-rules>
+
+- Each slice cuts a narrow but COMPLETE path through every layer (schema, API, UI, tests): vertical, NOT a horizontal slice of one layer
+- A completed slice is demoable or verifiable on its own
+- Each slice is sized to fit in a single fresh context window
+- Any prefactoring should be done first
+
+</vertical-slice-rules>
+
+Give each ticket its **blocking edges**: the other tickets that must complete before it can start. A ticket with no blockers can start immediately.
+
+**Wide refactors are the exception to vertical slicing.** A **wide refactor** is one mechanical change (rename a column, retype a shared symbol) whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as **expand–contract**. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches sized by blast radius (per package, per directory), each batch its own ticket blocked by the expand, keeping CI green batch to batch because the old form still exists. Finally contract: delete the old form once no caller remains, in a ticket blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify ticket; green is promised only there.
+
+### 4. Quiz the user
+
+Present the proposed breakdown as a numbered list. For each ticket, show:
+
+- **Title**: short descriptive name
+- **Blocked by**: which other tickets (if any) must complete first
+- **What it delivers**: the end-to-end behaviour this ticket makes work
+
+Ask the user:
+
+- Does the granularity feel right? (too coarse / too fine)
+- Are the blocking edges correct: does each ticket only depend on tickets that genuinely gate it?
+- Should any tickets be merged or split further?
+
+Iterate until the user approves the breakdown.
+
+### 5. Publish the tickets to the configured tracker
+
+Publish the approved tickets. **How** depends on the tracker `/setup-matt-pocock-skills` configured; the tickets are the same either way, only the shape of the blocking edges changes:
+
+- **Local files** → write one file per ticket under `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` in dependency order (blockers first). Each file's "Blocked by" lists the numbers/titles it depends on. Use the per-ticket file template below: one ticket per file, never a single combined file.
+- **A real issue tracker (GitHub, Linear, …)** → publish one issue per ticket in dependency order (blockers first) so each ticket's blocking edges can reference real identifiers. Use the platform's native blocking / sub-issue relationship where it has one; otherwise set each ticket's "Blocked by" to the blocking issues. Apply the `ready-for-agent` triage label unless instructed otherwise; the tickets are agent-grabbable by construction.
+
+Work the **frontier**: any ticket whose blockers are all done. For a purely linear chain that means top to bottom.
+
+Do NOT close or modify any parent issue.
+
+<local-ticket-template>
+
+# <NN>: <Ticket title>
+
+**What to build:** the end-to-end behaviour this ticket makes work, from the user's perspective, not a layer-by-layer implementation list.
+
+**Blocked by:** the numbers/titles of the tickets that gate this one, or "None (can start immediately)".
+
+**Status:** ready-for-agent
+
+- [ ] Acceptance criterion 1
+- [ ] Acceptance criterion 2
+
+</local-ticket-template>
+
+<issue-template>
+
+## Parent
+
+A reference to the parent issue on the tracker (if the source was an existing issue, otherwise omit this section).
+
+## What to build
+
+The end-to-end behaviour this ticket makes work, from the user's perspective, not layer-by-layer implementation.
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Blocked by
+
+- A reference to each blocking ticket, or "None (can start immediately)".
+
+</issue-template>
+
+In either form, avoid specific file paths or code snippets: they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts, not a working demo, just the important bits.

agentforge_framework/skills/to-tickets/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "To Tickets"
+  short_description: "Split a plan into tracer-bullet tickets"
+policy:
+  allow_implicit_invocation: false

agentforge_framework/skills/unslop/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: unslop
+description: Remove AI writing patterns from prose using either audit-only detection or a two-pass rewrite flow (diagnosis then reconstruction). Use this skill when editing, reviewing, or rewriting AI-generated content to make it sound human. Triggers on requests to "humanize", "de-slop", "fix AI text", "make it sound human", "remove AI patterns", or when reviewing text that contains obvious AI tells like "Here's the thing:", "Let that sink in", or "In today's fast-paced landscape". Also use when the user pastes text and says it "sounds like ChatGPT", "sounds robotic", "needs to sound more natural", or asks you to "clean up" drafted content before publishing.
+license: MIT
+user-invocable: true
+argument-hint: "[teach · cleanup · rewrite · mimic] [input]"
+metadata:
+  author: claytonkim
+  version: "2.3.0"
+---
+
+# Unslop
+
+Humanize AI-generated prose. Audit first. Rewrite only when the user asks for a rewrite.
+
+For every audit or rewrite, read [references/core-contract.md](references/core-contract.md).
+It is the single behavior contract. Command files define routing and mechanics;
+presets supply optional voice, but neither can override the core contract.
+
+## Routing
+
+**When the user invokes a sub-command (`/unslop teach ...`, `/unslop cleanup
+...`), you MUST read `references/commands/<command>.md` before acting.
+Non-optional — the command file defines the flow, and skipping it drops steps the
+user expects.** A bare `/unslop <text>` with no leading command word defaults to
+`rewrite`. If the first word does not match a command but the intent clearly maps
+to one (e.g. "flag the AI tells, don't change anything" → `cleanup` report-only),
+load that command file and proceed as if invoked.
+
+| Command | Purpose | File |
+|---------|---------|------|
+| `rewrite` | Default two-pass de-slop: diagnose, reconstruct under the guards, validate. | [references/commands/rewrite.md](references/commands/rewrite.md) |
+| `cleanup` | Co-writer: cheap detection, reviewable suggestions with contract gates; includes report-only "flag, change nothing". | [references/commands/cleanup.md](references/commands/cleanup.md) |
+| `teach` | Agent-driven voice building: harvest, approve, profile, layered card, scored demo. | [references/commands/teach.md](references/commands/teach.md) |
+| `mimic` | Voiced drafting or rewriting under the full gates; refine loop when one pass falls short. | [references/commands/mimic.md](references/commands/mimic.md) |
+| _maintenance_ | Turn a wild AI-ism into an eval row and a PR (not a top-level verb). | [references/commands/contribute.md](references/commands/contribute.md) |
+
+### Routing by phrase
+
+Sub-flows are reachable by their natural names without being top-level verbs.
+When the user says any of these, load the named file and jump to the flow:
+
+| The user says | Go to |
+|---------------|-------|
+| `audit` / "just flag it" / "don't change anything" | [references/commands/cleanup.md](references/commands/cleanup.md#report-only) |
+| `review` / "review this before I publish" | [references/commands/cleanup.md](references/commands/cleanup.md#report-only) |
+| `harvest` / "what writing of mine do you have?" | [references/commands/teach.md](references/commands/teach.md#1-gather-samples-harvest) |
+| `calibrate` / "the A/B game" / "quiz me on my voice" | [references/commands/teach.md](references/commands/teach.md#calibrate) |
+| `refine` / "keep pushing until it sounds like me" | [references/commands/mimic.md](references/commands/mimic.md#refine) |
+| voice check / "does this sound like me?" | [references/commands/mimic.md](references/commands/mimic.md#voice-check) |
+| "found a new AI-ism" / "add this tell" | [references/commands/contribute.md](references/commands/contribute.md) |
+
+## Interface
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `--preset` | Voice style: `crisp`, `warm`, `expert`, `story` | `crisp` |
+| `--strict` | Fail if rubric score < 32/40 | false |
+| `--report` | Flag AI patterns without changing the text (cleanup) | false |
+| Input | Text to transform (argument, file path, or stdin) | required |
+
+Read one preset from `presets/` before writing.
+
+| Preset | Style | Best For |
+|--------|-------|----------|
+| `crisp` | Short, direct, no fluff | Technical writing, documentation |
+| `warm` | Friendly, conversational | Emails, blog posts |
+| `expert` | Authoritative, confident | Thought leadership, articles |
+| `story` | Narrative flow, show don't tell | Case studies, personal posts |
+
+Rewrite, preservation, register, and validation behavior lives only in
+`references/core-contract.md`; do not recreate or override those rules here.
+
+## Output Format
+
+For a quick rewrite, return the cleaned text only. For audit-only (cleanup
+`--report`):
+
+```markdown
+## Issues Found
+
+- [Quoted issue, category, severity, why it reads as AI]
+
+## Assessment
+
+- [Which issues are clear problems]
+- [Which issues are judgment calls or context-dependent]
+```
+
+For strict or requested analysis:
+
+```markdown
+## Transformed Text
+
+[The humanized version]
+
+## Validation
+
+- Constraints: [X]/[Y] preserved
+- AI patterns: [N] remaining (was [M])
+- Structure: [pass/fail]
+- Readability: Grade [X], sentence variance [Y]
+- Change: [X]% from original
+- Score: [X]/40
+```
+
+## Reference Files
+
+| File | When to Read |
+|------|-------------|
+| `references/commands/*.md` | The routed command flows (rewrite, cleanup, teach, mimic, contribute). |
+| `references/pipeline.md` | Orchestrated tiered execution for multi-agent harnesses. |
+| `references/taboo-phrases.md` | Authoritative phrase catalog and scanner categories. |
+| `references/fact-preservation.md` | Constraint preservation rules. |
+| `references/rewrite-examples.md` | Executable before/after examples. |
+| `references/{mimic,harvest,calibrate}.md` | Voice-tool internals loaded by their routed command. |
+| `references/{rubric,edit-library,maintenance}.md` | Strict scoring, examples, and contribution procedures. |
+| `presets/*.md` | Voice-specific deltas. |
+
+## Maintenance
+
+The eval contracts define the product. Add scanner examples eval-first in
+`evals/fixtures/contracts/scanner-examples.json`; use
+`evals/adversarial-evals.json` for agent behavior and routing. Do not edit legacy
+`evals/evals.json`. New patterns need a false-negative example and a
+false-positive protection example. Agent behavior changes need a `skill` row
+and a regenerated shared benchmark. For the
+concrete procedures (add a phrase or structure, list current patterns, sync with
+Wikipedia's signs-of-AI-writing page), read `references/maintenance.md`. Found a
+new AI-ism in the wild? `references/commands/contribute.md` turns the exact
+snippet into a contract example and a structured PR, keeping both user-confirmation gates.

agentforge_framework/skills/unslop/evals/fixtures/silhouette/human_reference.json

@@ -0,0 +1,66 @@
+{
+  "description": "Human reference distribution for scripts/silhouette_scan.py. Regenerate with: python3 evals/check_silhouette.py --reference --write. median/iqr/n are derived from the sources below; fence and weight are research-validated constants (scratchpad/research/silhouette.md). The scorer scales each metric by max(iqr, fence): the sample IQR is degenerate at zero for these one-sided tells, so the fence is the effective scale.",
+  "penalty_threshold": 1.0,
+  "iqr_floor": 0.05,
+  "sources": [
+    "evals/fixtures/silhouette/corpus/human/01_linkedin.txt",
+    "evals/fixtures/silhouette/corpus/human/02_blog_intro.txt",
+    "evals/fixtures/silhouette/corpus/human/03_howto.txt",
+    "evals/fixtures/silhouette/corpus/human/04_essay.txt",
+    "evals/fixtures/silhouette/corpus/human/05_readme.txt",
+    "evals/fixtures/silhouette/corpus/human/06_email.txt",
+    "evals/fixtures/silhouette/corpus/human/07_personal_story.txt",
+    "evals/fixtures/silhouette/corpus/human/08_technical_explainer.txt",
+    "evals/fixtures/structure/struct02_bursty_narrative.md",
+    "evals/fixtures/structure/struct04_concrete_end.md",
+    "evals/fixtures/structure/struct10_varied_openers.md",
+    "evals/fixtures/structure/struct12_moderate_signpost.md",
+    "evals/fixtures/structure/struct15_one_closer.md",
+    "evals/fixtures/structure/struct16_parallel_enumeration.md",
+    "evals/fixtures/structure/struct17_academic_roadmap.md"
+  ],
+  "metric_order": [
+    "scaffold_opener_share",
+    "role_entropy_bits",
+    "heading_preview",
+    "preview_fulfillment",
+    "callback_content"
+  ],
+  "metrics": {
+    "scaffold_opener_share": {
+      "median": 0.0,
+      "iqr": 0.05,
+      "fence": 0.2,
+      "weight": 2.0,
+      "n": 15
+    },
+    "role_entropy_bits": {
+      "median": -0.0,
+      "iqr": 0.05,
+      "fence": 0.8,
+      "weight": 1.0,
+      "n": 15
+    },
+    "heading_preview": {
+      "median": 0.0,
+      "iqr": 0.05,
+      "fence": 0.2,
+      "weight": 1.0,
+      "n": 1
+    },
+    "preview_fulfillment": {
+      "median": 0.0,
+      "iqr": 0.05,
+      "fence": 0.25,
+      "weight": 1.0,
+      "n": 12
+    },
+    "callback_content": {
+      "median": 0.0,
+      "iqr": 0.05,
+      "fence": 0.3,
+      "weight": 1.5,
+      "n": 8
+    }
+  }
+}

agentforge_framework/skills/unslop/scripts/_lang.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""Shared cheap English-detection helpers for banned_phrase_scan.py,
+structure_scan.py, and silhouette_scan.py. All three scanners must decline the
+same non-English inputs, so this table and its two functions live in exactly
+one place.
+
+Also home to the shared prose-view helpers (tokenizer, markdown stripper,
+paragraph splitter) used by structure_scan.py and silhouette_scan.py. Those
+two scanners previously carried private copies of these functions that had
+drifted from each other (structure blanked blockquote lines, silhouette
+didn't; silhouette stripped **bold**, structure didn't). strip_markdown_for_prose
+below is the UNION of both original code paths, gated behind flags so each
+caller reconciles the drift deliberately rather than silently: structure_scan
+passes blank_blockquotes=True, silhouette_scan passes strip_bold=True."""
+
+from __future__ import annotations
+
+import re
+
+
+# A small set of high-frequency English function words used only for a cheap
+# language check. The words are chosen to be distinctively English: Spanish,
+# French, German, etc. rarely use them, so their share of tokens is a robust
+# signal without a language-model dependency.
+ENGLISH_FUNCTION_WORDS = frozenset({
+    "the", "and", "is", "are", "was", "were", "of", "to", "in", "that", "it",
+    "for", "with", "on", "this", "but", "not", "you", "have", "be", "as", "at",
+    "or", "we", "they", "will", "would", "there", "their", "what", "which",
+    "when", "from", "been", "has", "had", "its", "an", "by", "our", "your",
+    "if", "than", "then", "them", "these", "those", "about", "into", "over",
+    "after", "before", "how", "why", "where", "who", "can", "could", "should",
+    "do", "does", "did", "so", "out", "just", "more", "most", "some", "such",
+    "only", "also", "because", "while", "between", "through", "during", "being",
+})
+
+
+def english_function_share(text: str) -> float:
+    """Share of word tokens that are common English function words."""
+    tokens = re.findall(r"[a-z']+", text.lower())
+    if not tokens:
+        return 1.0
+    hits = sum(1 for t in tokens if t in ENGLISH_FUNCTION_WORDS)
+    return hits / len(tokens)
+
+
+def is_probably_english(text: str, threshold: float = 0.10, min_tokens: int = 15) -> bool:
+    """Cheap English detector backing a graceful non-English decline.
+
+    Conservative on purpose: inputs below ``min_tokens`` are always treated as
+    English (too little signal to decline), and ``threshold`` is low enough that
+    even terse or ESL-flavored English clears it. Only prose with almost no
+    English function words (i.e. another language) is declined.
+    """
+    tokens = re.findall(r"[a-z']+", text.lower())
+    if len(tokens) < min_tokens:
+        return True
+    return english_function_share(text) >= threshold
+
+
+def words(text: str) -> list[str]:
+    return re.findall(r"[A-Za-z0-9]+(?:[-'][A-Za-z0-9]+)?", text.lower())
+
+
+def strip_markdown_for_prose(
+    text: str, *, blank_blockquotes: bool = False, strip_bold: bool = False
+) -> str:
+    """Strip markdown structure down to a prose view for cadence/discourse
+    metrics. UNION of structure_scan's and silhouette_scan's original
+    strippers -- each original branch is preserved verbatim, gated behind the
+    flag that reproduces that caller's exact prior behavior.
+
+    blank_blockquotes=True reproduces structure_scan's prior strip (blanks
+    both blockquote and heading lines in one combined check). strip_bold=True
+    reproduces silhouette_scan's prior strip (also collapses **bold** markers
+    after list/ordinal stripping).
+    """
+    text = re.sub(r"```[\s\S]*?```", "\n\n", text)
+    kept = []
+    for line in text.splitlines():
+        if blank_blockquotes:
+            if re.match(r"\s*>", line) or re.match(r"\s{0,3}#{1,6}\s+", line):
+                kept.append("")
+                continue
+        else:
+            if re.match(r"\s{0,3}#{1,6}\s+", line):
+                kept.append("")  # drop heading text from the prose view
+                continue
+        line = re.sub(r"^\s*[-*+]\s+", "", line)
+        line = re.sub(r"^\s*\d+[.)]\s+", "", line)
+        if strip_bold:
+            line = re.sub(r"\*\*([^*]+)\*\*", r"\1", line)
+        kept.append(line)
+    return "\n".join(kept)
+
+
+def paragraphs(
+    text: str, *, blank_blockquotes: bool = False, strip_bold: bool = False
+) -> list[str]:
+    stripped = strip_markdown_for_prose(
+        text, blank_blockquotes=blank_blockquotes, strip_bold=strip_bold
+    )
+    return [
+        re.sub(r"\s+", " ", p).strip()
+        for p in re.split(r"\n\s*\n", stripped)
+        if p.strip()
+    ]