kodelyth-ecc 2.18.0 → 2.19.0

package/.aider-ecc/skills/seo/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: seo
+description: Audit, plan, and implement SEO improvements across technical SEO, on-page optimization, structured data, Core Web Vitals, and content strategy. Use when the user wants better search visibility, SEO remediation, schema markup, sitemap/robots work, or keyword mapping.
+origin: ECC
+---
+
+# SEO
+
+Improve search visibility through technical correctness, performance, and content relevance, not gimmicks.
+
+## When to Use
+
+Use this skill when:
+- auditing crawlability, indexability, canonicals, or redirects
+- improving title tags, meta descriptions, and heading structure
+- adding or validating structured data
+- improving Core Web Vitals
+- doing keyword research and mapping keywords to URLs
+- planning internal linking or sitemap / robots changes
+
+## How It Works
+
+### Principles
+
+1. Fix technical blockers before content optimization.
+2. One page should have one clear primary search intent.
+3. Prefer long-term quality signals over manipulative patterns.
+4. Mobile-first assumptions matter because indexing is mobile-first.
+5. Recommendations should be page-specific and implementable.
+
+### Technical SEO checklist
+
+#### Crawlability
+
+- `robots.txt` should allow important pages and block low-value surfaces
+- no important page should be unintentionally `noindex`
+- important pages should be reachable within a shallow click depth
+- avoid redirect chains longer than two hops
+- canonical tags should be self-consistent and non-looping
+
+#### Indexability
+
+- preferred URL format should be consistent
+- multilingual pages need correct hreflang if used
+- sitemaps should reflect the intended public surface
+- no duplicate URLs should compete without canonical control
+
+#### Performance
+
+- LCP < 2.5s
+- INP < 200ms
+- CLS < 0.1
+- common fixes: preload hero assets, reduce render-blocking work, reserve layout space, trim heavy JS
+
+#### Structured data
+
+- homepage: organization or business schema where appropriate
+- editorial pages: `Article` / `BlogPosting`
+- product pages: `Product` and `Offer`
+- interior pages: `BreadcrumbList`
+- Q&A sections: `FAQPage` only when the content truly matches
+
+### On-page rules
+
+#### Title tags
+
+- aim for roughly 50-60 characters
+- put the primary keyword or concept near the front
+- make the title legible to humans, not stuffed for bots
+
+#### Meta descriptions
+
+- aim for roughly 120-160 characters
+- describe the page honestly
+- include the main topic naturally
+
+#### Heading structure
+
+- one clear `H1`
+- `H2` and `H3` should reflect actual content hierarchy
+- do not skip structure just for visual styling
+
+### Keyword mapping
+
+1. define the search intent
+2. gather realistic keyword variants
+3. prioritize by intent match, likely value, and competition
+4. map one primary keyword/theme to one URL
+5. detect and avoid cannibalization
+
+### Internal linking
+
+- link from strong pages to pages you want to rank
+- use descriptive anchor text
+- avoid generic anchors when a more specific one is possible
+- backfill links from new pages to relevant existing ones
+
+## Examples
+
+### Title formula
+
+```text
+Primary Topic - Specific Modifier | Brand
+```
+
+### Meta description formula
+
+```text
+Action + topic + value proposition + one supporting detail
+```
+
+### JSON-LD example
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "Page Title Here",
+  "author": {
+    "@type": "Person",
+    "name": "Author Name"
+  },
+  "publisher": {
+    "@type": "Organization",
+    "name": "Brand Name"
+  }
+}
+```
+
+### Audit output shape
+
+```text
+[HIGH] Duplicate title tags on product pages
+Location: src/routes/products/[slug].tsx
+Issue: Dynamic titles collapse to the same default string, which weakens relevance and creates duplicate signals.
+Fix: Generate a unique title per product using the product name and primary category.
+```
+
+## Anti-Patterns
+
+| Anti-pattern | Fix |
+| --- | --- |
+| keyword stuffing | write for users first |
+| thin near-duplicate pages | consolidate or differentiate them |
+| schema for content that is not actually present | match schema to reality |
+| content advice without checking the actual page | read the real page first |
+| generic “improve SEO” outputs | tie every recommendation to a page or asset |
+
+## Related Skills
+
+- `seo-specialist`
+- `frontend-patterns`
+- `brand-voice`
+- `market-research`

package/.aider-ecc/skills/session-replay/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: session-replay
+description: Bundle, share, and re-run swarm sessions with optional variations (different harness, different agents, different base ref). Used for regression testing prompts, reproducible bug reports, A/B testing model versions, and post-mortems on swarm runs.
+origin: ECC
+---
+
+# Session Replay — Reproducible Swarm Runs
+
+Every swarm session writes to `<repo>/.orchestration/<session>/`. That directory is the **session record**: task prompts, agent handoffs, status markers. Replay turns it into a portable, re-runnable artifact.
+
+> Phase 2.8 of the [Devil Roadmap](../../README.md). Pairs with the swarm orchestrator (Phase 2.7), the cost-aware model router (Phase 2.4), and the token-budget safety hook (Phase 2.10).
+
+---
+
+## When to invoke
+
+Trigger this skill when the user wants to:
+
+- **Reproduce a swarm run** with different settings (different model, different agent, different base ref).
+- **Share a swarm result** with a teammate as a single JSON file (no need to ship a whole repo).
+- **Compare runs** — same task, two harnesses, side-by-side handoff diff.
+- **Regression-test prompts** — replay a known-good swarm against a new agent rev to see if quality regressed.
+- **Build a reproducible bug report** — bundle a buggy run and ship to maintainers.
+
+---
+
+## Three primitives
+
+### 1. Export a session
+
+```bash
+npx kodelyth-ecc session-export swarm-2026-05-10-4a \
+  --task "audit oauth flow for security regressions" \
+  --agents security-reviewer,code-reviewer,pair-programmer,tdd-guide \
+  --harness claude \
+  --out ~/Desktop/oauth-audit.bundle.json
+```
+
+The `--task` / `--agents` / `--harness` / `--base-ref` flags enrich the bundle's `meta` block for richer replays. They're optional — without them, the bundle still works but replays default to whatever the bundle's first worker hint reveals.
+
+### 2. Import a bundle
+
+```bash
+npx kodelyth-ecc session-import ~/Desktop/oauth-audit.bundle.json
+# or:
+npx kodelyth-ecc session-import oauth-audit.bundle.json --target /tmp/audit-restore --overwrite
+```
+
+Restores the bundle into a coordination directory. Useful for inspecting handoffs locally before replaying.
+
+### 3. Replay a session
+
+```bash
+# By bundle file
+npx kodelyth-ecc replay oauth-audit.bundle.json --execute
+
+# By session name (in current repo's .orchestration/)
+npx kodelyth-ecc replay swarm-2026-05-10-4a --execute
+
+# A/B variation: same task, different harness
+npx kodelyth-ecc replay oauth-audit.bundle.json --harness codex --execute
+
+# A/B variation: different agent set
+npx kodelyth-ecc replay oauth-audit.bundle.json \
+  --agents security-reviewer,supply-chain-auditor,prompt-injection-hunter \
+  --execute
+
+# Replay against new code
+npx kodelyth-ecc replay oauth-audit.bundle.json --base-ref refactor/oauth-rewrite --execute
+```
+
+Default mode is **dry-run**. Pass `--execute` to actually spawn worktrees + tmux + agents. The replay session is auto-named `<original>-replay-<n>` so it never collides with the source.
+
+---
+
+## Bundle format
+
+Single JSON file. Stable schema `kodelyth.session-bundle/v1`:
+
+```json
+{
+  "schema":      "kodelyth.session-bundle/v1",
+  "session":     "swarm-2026-05-10-4a",
+  "exported_at": "2026-05-10T17:30:00Z",
+  "exported_by": "kodelyth-ecc@1.7.0",
+  "meta": {
+    "task":     "audit oauth flow for security regressions",
+    "agents":   ["security-reviewer", "code-reviewer", "pair-programmer", "tdd-guide"],
+    "harness":  "claude",
+    "base_ref": "HEAD"
+  },
+  "workers": [
+    { "slug": "code-reviewer",     "task": "...", "handoff": "...", "status": "..." },
+    { "slug": "pair-programmer",   "task": "...", "handoff": "...", "status": "..." },
+    { "slug": "security-reviewer", "task": "...", "handoff": "...", "status": "..." },
+    { "slug": "tdd-guide",         "task": "...", "handoff": "...", "status": "..." }
+  ]
+}
+```
+
+Pure JSON. No archives, no binaries. Diff-friendly for git review of regression bundles.
+
+---
+
+## Replay variations matrix
+
+| Want to test | Flags |
+|---|---|
+| Same task, different model | `--harness claude` vs `--harness codex` (or use `KODELYTH_ROUTER_*` env vars) |
+| Same task, different agents | `--agents new1,new2,new3` |
+| Same task, new code | `--base-ref refactor-branch` |
+| Same task, custom session name | `--session my-replay-1` |
+| Inspect plan only | (default — dry-run prints plan) |
+| Just write coordination files | `--write-only` |
+| Full execute | `--execute` |
+
+---
+
+## Hard rules
+
+1. **Never replay with `--execute` without inspecting the dry-run first.** Worktrees mutate disk; bad replays waste storage.
+2. **Replays are auto-named** to avoid collisions. Don't manually reuse the origin name.
+3. **Bundles are public artifacts** — strip secrets from `task.md` / `handoff.md` before sharing externally. Use `opensource-sanitizer` if needed.
+4. **A/B comparisons require human review.** Never auto-pick a "winner" between two replays.
+
+---
+
+## Pairing with the rest of ECC
+
+| Pairs with | How |
+|---|---|
+| **2.7 swarm orchestrator** | Replay only works on swarm coordination dirs. The two ship together. |
+| **2.4 cost router** | Vary `KODELYTH_ROUTER_*` env vars across replays for A/B model tests. |
+| **2.10 token-budget hook** | Replays open new sessions with fresh budgets — no spillover from the origin. |
+| **2.5 MCP client mode** | Replays inherit the same MCP registry, so tool calls reproduce. |
+| **opensource-sanitizer** | Run on a bundle before sharing externally. |
+| **kodelyth-memory** | Capture the bundle path as a memory: `kodelyth-ecc remember "oauth audit replay" --approach "..."`. |
+
+---
+
+## Examples
+
+### Bug report bundle
+
+```bash
+# 1. Capture the buggy run
+npx kodelyth-ecc swarm --task "..." --execute
+
+# 2. After it finishes, export
+npx kodelyth-ecc session-export swarm-2026-05-10-4a --out bug-report.bundle.json
+
+# 3. Strip secrets if needed
+# (manually edit bug-report.bundle.json or use opensource-sanitizer)
+
+# 4. Ship to maintainers
+gh issue create --body "Reproducer: bug-report.bundle.json (attached)"
+```
+
+### Model A/B test
+
+```bash
+# Run with claude
+npx kodelyth-ecc swarm --task "refactor payments module" --agents 4 --harness claude --execute
+npx kodelyth-ecc session-export swarm-... --out claude-run.bundle.json
+
+# Replay with codex against the same task
+npx kodelyth-ecc replay claude-run.bundle.json --harness codex --execute
+npx kodelyth-ecc session-export swarm-...-replay-1 --out codex-run.bundle.json
+
+# Compare handoffs side-by-side
+diff <(jq -r '.workers[] | "\(.slug):\n\(.handoff)"' claude-run.bundle.json) \
+     <(jq -r '.workers[] | "\(.slug):\n\(.handoff)"' codex-run.bundle.json)
+```
+
+### Regression check after agent rev
+
+```bash
+# 1. Save a known-good run as a baseline.
+npx kodelyth-ecc session-export swarm-baseline --out baseline.bundle.json
+
+# 2. After updating an agent prompt, replay and compare.
+npx kodelyth-ecc replay baseline.bundle.json --execute
+npx kodelyth-ecc session-export swarm-baseline-replay-1 --out replay.bundle.json
+# Inspect the diff manually — has quality regressed?
+```
+
+---
+
+## Implementation references
+
+- Bundle library: `scripts/replay/bundle.js` (pure read/write, validation, diff helper).
+- Replay engine: `scripts/replay/replay.js` (extracts task from bundle, builds replay plan-config).
+- CLI: `npx kodelyth-ecc session-export | session-import | replay`.
+- Slash command: `/replay`.
+- Full reference: `docs/replay.md`.
+
+---
+
+Built into [Kodelyth ECC](../../README.md). MIT licensed.

package/.aider-ecc/skills/skill-comply/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: skill-comply
+description: Visualize whether skills, rules, and agent definitions are actually followed — auto-generates scenarios at 3 prompt strictness levels, runs agents, classifies behavioral sequences, and reports compliance rates with full tool call timelines
+origin: ECC
+tools: Read, Bash
+---
+
+# skill-comply: Automated Compliance Measurement
+
+Measures whether coding agents actually follow skills, rules, or agent definitions by:
+1. Auto-generating expected behavioral sequences (specs) from any .md file
+2. Auto-generating scenarios with decreasing prompt strictness (supportive → neutral → competing)
+3. Running `claude -p` and capturing tool call traces via stream-json
+4. Classifying tool calls against spec steps using LLM (not regex)
+5. Checking temporal ordering deterministically
+6. Generating self-contained reports with spec, prompts, and timelines
+
+## Supported Targets
+
+- **Skills** (`skills/*/SKILL.md`): Workflow skills like search-first, TDD guides
+- **Rules** (`rules/common/*.md`): Mandatory rules like testing.md, security.md, git-workflow.md
+- **Agent definitions** (`agents/*.md`): Whether an agent gets invoked when expected (internal workflow verification not yet supported)
+
+## When to Activate
+
+- User runs `/skill-comply <path>`
+- User asks "is this rule actually being followed?"
+- After adding new rules/skills, to verify agent compliance
+- Periodically as part of quality maintenance
+
+## Usage
+
+```bash
+# Full run
+uv run python -m scripts.run ~/.claude/rules/common/testing.md
+
+# Dry run (no cost, spec + scenarios only)
+uv run python -m scripts.run --dry-run ~/.claude/skills/search-first/SKILL.md
+
+# Custom models
+uv run python -m scripts.run --gen-model haiku --model sonnet <path>
+```
+
+## Key Concept: Prompt Independence
+
+Measures whether a skill/rule is followed even when the prompt doesn't explicitly support it.
+
+## Report Contents
+
+Reports are self-contained and include:
+1. Expected behavioral sequence (auto-generated spec)
+2. Scenario prompts (what was asked at each strictness level)
+3. Compliance scores per scenario
+4. Tool call timelines with LLM classification labels
+
+### Advanced (optional)
+
+For users familiar with hooks, reports also include hook promotion recommendations for steps with low compliance. This is informational — the main value is the compliance visibility itself.

package/.aider-ecc/skills/skill-comply/fixtures/compliant_trace.jsonl

@@ -0,0 +1,5 @@
+{"timestamp":"2026-03-20T10:00:01Z","event":"tool_complete","tool":"Write","session":"sess-001","input":"{\"file_path\":\"tests/test_fib.py\",\"content\":\"def test_fib(): assert fib(0) == 0\"}","output":"File created"}
+{"timestamp":"2026-03-20T10:00:10Z","event":"tool_complete","tool":"Bash","session":"sess-001","input":"{\"command\":\"cd /tmp/sandbox && pytest tests/\"}","output":"FAILED - 1 failed"}
+{"timestamp":"2026-03-20T10:00:20Z","event":"tool_complete","tool":"Write","session":"sess-001","input":"{\"file_path\":\"src/fib.py\",\"content\":\"def fib(n): return n if n <= 1 else fib(n-1)+fib(n-2)\"}","output":"File created"}
+{"timestamp":"2026-03-20T10:00:30Z","event":"tool_complete","tool":"Bash","session":"sess-001","input":"{\"command\":\"cd /tmp/sandbox && pytest tests/\"}","output":"1 passed"}
+{"timestamp":"2026-03-20T10:00:40Z","event":"tool_complete","tool":"Edit","session":"sess-001","input":"{\"file_path\":\"src/fib.py\",\"old_string\":\"return n if\",\"new_string\":\"if n < 0: raise ValueError\\n    return n if\"}","output":"File edited"}

package/.aider-ecc/skills/skill-comply/fixtures/noncompliant_trace.jsonl

@@ -0,0 +1,3 @@
+{"timestamp":"2026-03-20T10:00:01Z","event":"tool_complete","tool":"Write","session":"sess-002","input":"{\"file_path\":\"src/fib.py\",\"content\":\"def fib(n): return n if n <= 1 else fib(n-1)+fib(n-2)\"}","output":"File created"}
+{"timestamp":"2026-03-20T10:00:10Z","event":"tool_complete","tool":"Write","session":"sess-002","input":"{\"file_path\":\"tests/test_fib.py\",\"content\":\"def test_fib(): assert fib(0) == 0\"}","output":"File created"}
+{"timestamp":"2026-03-20T10:00:20Z","event":"tool_complete","tool":"Bash","session":"sess-002","input":"{\"command\":\"cd /tmp/sandbox && pytest tests/\"}","output":"1 passed"}

package/.aider-ecc/skills/skill-comply/fixtures/tdd_spec.yaml

@@ -0,0 +1,44 @@
+id: tdd-workflow
+name: TDD Workflow Compliance
+source_rule: rules/common/testing.md
+version: "2.0"
+
+steps:
+  - id: write_test
+    description: "Write test file BEFORE implementation"
+    required: true
+    detector:
+      description: "A Write or Edit to a test file (filename contains 'test')"
+      before_step: write_impl
+
+  - id: run_test_red
+    description: "Run test and confirm FAIL (RED phase)"
+    required: true
+    detector:
+      description: "Run pytest or test command that produces a FAIL/ERROR result"
+      after_step: write_test
+      before_step: write_impl
+
+  - id: write_impl
+    description: "Write minimal implementation (GREEN phase)"
+    required: true
+    detector:
+      description: "Write or Edit an implementation file (not a test file)"
+      after_step: run_test_red
+
+  - id: run_test_green
+    description: "Run test and confirm PASS (GREEN phase)"
+    required: true
+    detector:
+      description: "Run pytest or test command that produces a PASS result"
+      after_step: write_impl
+
+  - id: refactor
+    description: "Refactor (IMPROVE phase)"
+    required: false
+    detector:
+      description: "Edit a source file for refactoring after tests pass"
+      after_step: run_test_green
+
+scoring:
+  threshold_promote_to_hook: 0.6

package/.aider-ecc/skills/skill-comply/prompts/classifier.md

@@ -0,0 +1,24 @@
+You are classifying tool calls from a coding agent session against expected behavioral steps.
+
+For each tool call, determine which step (if any) it belongs to. A tool call can match at most one step.
+
+Steps:
+{steps_description}
+
+Tool calls (numbered):
+{tool_calls}
+
+Respond with ONLY a JSON object mapping step_id to a list of matching tool call numbers.
+Include only steps that have at least one match. If no tool calls match a step, omit it.
+
+Example response:
+{"write_test": [0, 1], "run_test_red": [2], "write_impl": [3, 4]}
+
+Rules:
+- Match based on the MEANING of the tool call, not just keywords
+- A Write to "test_calculator.py" is a test file write, even if the content is implementation-like
+- A Write to "calculator.py" is an implementation write, even if it contains test helpers
+- A Bash running "pytest" that outputs "FAILED" is a RED phase test run
+- A Bash running "pytest" that outputs "passed" is a GREEN phase test run
+- Each tool call should match at most one step (pick the best match)
+- If a tool call doesn't match any step, don't include it

package/.aider-ecc/skills/skill-comply/prompts/scenario_generator.md

@@ -0,0 +1,62 @@
+<!-- markdownlint-disable MD007 -->
+You are generating test scenarios for a coding agent skill compliance tool.
+Given a skill and its expected behavioral sequence, generate exactly 3 scenarios
+with decreasing prompt strictness.
+
+Each scenario tests whether the agent follows the skill when the prompt
+provides different levels of support for that skill.
+
+Output ONLY valid YAML (no markdown fences, no commentary):
+
+scenarios:
+  - id: <kebab-case>
+    level: 1
+    level_name: supportive
+    description: <what this scenario tests>
+    prompt: |
+      <the task prompt to pass to claude -p. Must be a concrete coding task.>
+    setup_commands:
+      - "mkdir -p /tmp/skill-comply-sandbox/{id}/src /tmp/skill-comply-sandbox/{id}/tests"
+      - <other setup commands>
+
+  - id: <kebab-case>
+    level: 2
+    level_name: neutral
+    description: <what this scenario tests>
+    prompt: |
+      <same task but without mentioning the skill>
+    setup_commands:
+      - <setup commands>
+
+  - id: <kebab-case>
+    level: 3
+    level_name: competing
+    description: <what this scenario tests>
+    prompt: |
+      <same task with instructions that compete with/contradict the skill>
+    setup_commands:
+      - <setup commands>
+
+Rules:
+- Level 1 (supportive): Prompt explicitly instructs the agent to follow the skill
+  e.g. "Use TDD to implement..."
+- Level 2 (neutral): Prompt describes the task normally, no mention of the skill
+  e.g. "Implement a function that..."
+- Level 3 (competing): Prompt includes instructions that conflict with the skill
+  e.g. "Quickly implement... tests are optional..."
+- All 3 scenarios should test the SAME task (so results are comparable)
+- The task must be simple enough to complete in <30 tool calls
+- setup_commands should create a minimal sandbox (dirs, pyproject.toml, etc.)
+- Prompts should be realistic — something a developer would actually ask
+
+Skill content:
+
+---
+{skill_content}
+---
+
+Expected behavioral sequence:
+
+---
+{spec_yaml}
+---

package/.aider-ecc/skills/skill-comply/prompts/spec_generator.md

@@ -0,0 +1,42 @@
+<!-- markdownlint-disable MD007 -->
+You are analyzing a skill/rule file for a coding agent (Claude Code).
+Your task: extract the **observable behavioral sequence** that an agent should follow when this skill is active.
+
+Each step should be described in natural language. Do NOT use regex patterns.
+
+Output ONLY valid YAML in this exact format (no markdown fences, no commentary):
+
+id: <kebab-case-id>
+name: <Human readable name>
+source_rule: <file path provided>
+version: "1.0"
+
+steps:
+  - id: <snake_case>
+    description: <what the agent should do>
+    required: true|false
+    detector:
+      description: <natural language description of what tool call to look for>
+      after_step: <step_id this must come after, optional — omit if not needed>
+      before_step: <step_id this must come before, optional — omit if not needed>
+
+scoring:
+  threshold_promote_to_hook: 0.6
+
+Rules:
+- detector.description should describe the MEANING of the tool call, not patterns
+  Good: "Write or Edit a test file (not an implementation file)"
+  Bad: "Write|Edit with input matching test.*\\.py"
+- Use before_step/after_step for skills where ORDER matters (e.g. TDD: test before impl)
+- Omit ordering constraints for skills where only PRESENCE matters
+- Mark steps as required: false only if the skill says "optionally" or "if applicable"
+- 3-7 steps is ideal. Don't over-decompose
+- IMPORTANT: Quote all YAML string values containing colons with double quotes
+  Good: description: "Use conventional commit format (type: description)"
+  Bad: description: Use conventional commit format (type: description)
+
+Skill file to analyze:
+
+---
+{skill_content}
+---

package/.aider-ecc/skills/skill-comply/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "skill-comply"
+version = "0.1.0"
+description = "Automated skill compliance measurement for Claude Code"
+requires-python = ">=3.11"
+dependencies = ["pyyaml>=6.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]