minimal-vibe-coding-kit 0.4.1 → 0.4.2

package/.grok/skills/agentshield-security-review/references/native-install.md

@@ -0,0 +1,97 @@
+# Native Claude Code and Codex Install Pattern
+
+Keep one canonical skill and add thin harness adapters.
+
+## Shared skill location
+
+Recommended repo layout:
+
+```text
+.vibekit/skills/agentshield-security-review/SKILL.md
+.vibekit/skills/agentshield-security-review/references/review-checklist.md
+.vibekit/skills/agentshield-security-review/references/report-template.md
+.vibekit/skills/agentshield-security-review/scripts/agentshield_repo_probe.py
+.vibekit/commands/security-scan.md
+.codex-plugin/plugin.json
+.claude-plugin/plugin.json
+```
+
+## Claude Code command shim
+
+Create `.vibekit/commands/security-scan.md` or `.claude/commands/security-scan.md`:
+
+```markdown
+---
+description: Run an AgentShield-style security scan against agent, hook, MCP, permission, skill, command, Claude, and Codex surfaces.
+agent: security-reviewer
+subtask: true
+---
+
+# Security Scan
+
+Run the shared `agentshield-security-review` skill against the current repo or the target path.
+
+## Usage
+
+`/security-scan [path] [--format text|json|markdown|html] [--min-severity low|medium|high|critical] [--fix]`
+
+Prefer the deterministic scanner:
+
+```bash
+npx ecc-agentshield scan --path "${TARGET_PATH:-.}" --format text
+```
+
+If `--fix` is requested, summarize planned safe fixes first, apply only scanner-marked safe fixes, then re-run the scan.
+
+Return grade, score, severity counts, active paths, critical/high findings, and remediation order.
+```
+
+## Codex plugin pointer
+
+Use the repo-level Codex plugin manifest to point Codex at the same `.vibekit/skills/` directory. Exact schema may vary by Codex plugin version, so preserve the existing repo schema and ensure it references the canonical `.vibekit/skills/` directory rather than a copied skill body.
+
+Example intent:
+
+```json
+{
+  "name": "your-repo",
+  "version": "0.1.0",
+  "skills": "./.vibekit/skills",
+  "mcp": "./.mcp.json"
+}
+```
+
+## CI gate
+
+Add a GitHub Actions job when you want agent config changes to fail builds:
+
+```yaml
+name: agent-security
+on:
+  pull_request:
+    paths:
+      - "CLAUDE.md"
+      - "AGENTS.md"
+      - ".claude/**"
+      - ".codex/**"
+      - ".codex-plugin/**"
+      - ".claude-plugin/**"
+      - ".agents/**"
+      - "agents/**"
+      - ".vibekit/skills/**"
+      - ".vibekit/commands/**"
+      - "hooks/**"
+      - ".mcp.json"
+      - "mcp-configs/**"
+
+jobs:
+  agentshield:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: Run AgentShield
+        run: npx ecc-agentshield scan --path . --format text --min-severity medium
+```

package/.grok/skills/agentshield-security-review/references/report-template.md

@@ -0,0 +1,54 @@
+# Security Review Report Template
+
+Use this structure for final reports.
+
+## Summary
+
+- Scan mode:
+- Grade/score:
+- Repo root:
+- Harnesses found:
+- Overall risk:
+
+## Commands run
+
+```bash
+# commands here
+```
+
+## Active surfaces found
+
+| Surface | Paths | Runtime confidence |
+|---|---|---|
+| Claude |  |  |
+| Codex |  |  |
+| Shared skills |  |  |
+| Hooks |  |  |
+| MCP |  |  |
+| CI/plugin |  |  |
+
+## Critical/high findings
+
+| Severity | Confidence | Path | Issue | Why it matters | Fix | Auto-fix safe? |
+|---|---|---|---|---|---|---|
+
+## Medium/low findings
+
+Group by theme: permissions, hooks, MCP, prompts, skills, .vibekit/docs/examples.
+
+## Remediation order
+
+1. Remove or rotate exposed secrets.
+2. Restrict shell/tool permissions.
+3. Pin or sandbox MCP/package execution.
+4. Harden hooks and quote/sanitize variables.
+5. Add CI gate.
+6. Remove duplicate divergent Claude/Codex skill copies.
+7. Re-run scan and confirm grade improvement.
+
+## Native integration status
+
+- Claude Code:
+- Codex:
+- Shared skill source:
+- Drift risks:

package/.grok/skills/agentshield-security-review/references/review-checklist.md

@@ -0,0 +1,45 @@
+# AgentShield Manual Review Checklist
+
+Use this checklist when `ecc-agentshield` is unavailable or when reviewing scanner output.
+
+## Critical findings
+
+Flag as critical when a runtime-active agent surface contains any of these:
+
+- Hardcoded API keys, tokens, private keys, passwords, or webhook secrets.
+- Unrestricted shell permissions such as `Bash` wildcard permissions, `bash -c` passthroughs, or unrestricted command execution in hooks.
+- Hook command injection risk from unsanitized variables such as file paths, branch names, issue titles, PR text, or model-provided arguments.
+- MCP server definitions that execute shell commands, pull remote code dynamically, or expose broad filesystem/network access without pinning or sandboxing.
+- Instructions that tell the agent to ignore system/developer safety boundaries or auto-run commands from untrusted content.
+
+## High findings
+
+Flag as high when active config contains:
+
+- Missing deny lists for destructive commands.
+- Broad tool permissions for agents that only need read/review access.
+- `npx` auto-yes flags, curl-piped-to-shell, or remote install during runtime without pinning/checksum.
+- Agents that ingest untrusted web/issues/PRs without prompt-injection boundaries.
+- Hooks that send repository content to remote endpoints without explicit disclosure.
+
+## Medium findings
+
+Flag as medium when active config contains:
+
+- Silent failure suppression such as always-success shell fallbacks, stderr suppression, or broad `try/catch` around security checks.
+- Missing descriptions for MCP servers or agent purposes.
+- Duplicate Claude/Codex skill copies likely to drift.
+- Lack of CI security scan for agent config changes.
+
+## Low/info findings
+
+Flag as low/info for documentation gaps, inactive examples, or optional templates that do not affect runtime.
+
+## Review confidence
+
+Use these labels:
+
+- `active-runtime`: loaded by current harness or plugin manifest.
+- `repo-template`: checked-in template that users may copy.
+- `documentation-example`: not active unless copied.
+- `unknown`: unable to determine loading path.

package/.grok/skills/agentshield-security-review/scripts/agentshield_repo_probe.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Inventory AgentShield-relevant AI coding-agent surfaces in a repository.
+
+This script is intentionally read-only. It does not execute hooks, package scripts,
+MCP servers, or installer commands.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Iterable
+
+PATTERNS = {
+    "repo_instructions": ["CLAUDE.md", "AGENTS.md", ".github/copilot-instructions.md"],
+    "claude": [".claude", ".claude-plugin", "agents"],
+    "codex": [".codex", ".codex-plugin"],
+    "grok": [".grok"],
+    "shared_skills": [".vibekit/skills", ".claude/skills", ".cursor/skills", ".agents/skills", ".grok/skills", "skills"],
+    "shared_commands": [".vibekit/commands"],
+    "kit_scripts": [".vibekit/scripts"],
+    "hooks": ["hooks", ".claude/hooks", ".agents/hooks", ".grok/hooks"],
+    "mcp": [".mcp.json", "mcp.json", "mcp-configs"],
+    "ci": [".github/workflows"],
+}
+
+SUSPICIOUS_TEXT = [
+    "Bash" + "(*)",
+    "npx" + " -y",
+    "curl" + " | sh",
+    "wget" + " | sh",
+    "||" + " true",
+    "2>" + "/dev/null",
+    "ignore previous" + " instructions",
+    "ignore all previous" + " instructions",
+    "ANTHROPIC" + "_API_KEY=",
+    "OPENAI" + "_API_KEY=",
+    "GITHUB" + "_TOKEN=",
+]
+
+
+def iter_files(path: Path) -> Iterable[Path]:
+    if path.is_file():
+        yield path
+    elif path.is_dir():
+        for child in path.rglob("*"):
+            if child.is_file() and ".git" not in child.parts:
+                yield child
+
+
+def safe_read(path: Path, limit: int = 200_000) -> str:
+    try:
+        data = path.read_bytes()[:limit]
+        return data.decode("utf-8", errors="ignore")
+    except OSError:
+        return ""
+
+
+def deny_block_lines(text: str) -> set[int]:
+    """Line indexes inside a permissions deny array (JSON `"deny": [` or TOML `deny = [`).
+
+    Deny rules quote dangerous patterns in order to block them, so a marker on
+    those lines is defensive, not suspicious. Allow/ask blocks are still scanned.
+    """
+    covered: set[int] = set()
+    inside = False
+    for idx, line in enumerate(text.splitlines()):
+        stripped = line.strip()
+        if not inside and "[" in stripped and ('"deny"' in stripped or stripped.startswith("deny =") or stripped.startswith("deny=")):
+            covered.add(idx)
+            inside = "]" not in stripped.split("[", 1)[1]
+            continue
+        if inside:
+            covered.add(idx)
+            if "]" in stripped:
+                inside = False
+    return covered
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Inventory Claude/Codex AgentShield surfaces")
+    parser.add_argument("path", nargs="?", default=".", help="Repository root")
+    parser.add_argument("--json", action="store_true", help="Emit JSON")
+    args = parser.parse_args()
+
+    root = Path(args.path).resolve()
+    result: dict[str, object] = {"repo_root": str(root), "surfaces": {}, "suspicious_markers": []}
+
+    surfaces: dict[str, list[str]] = {}
+    suspicious: list[dict[str, str]] = []
+
+    for category, patterns in PATTERNS.items():
+        found: list[str] = []
+        for pattern in patterns:
+            candidate = root / pattern
+            if candidate.exists():
+                found.append(str(candidate.relative_to(root)))
+                for file_path in iter_files(candidate):
+                    if file_path.suffix.lower() not in {".md", ".json", ".toml", ".yaml", ".yml", ".sh", ".js", ".ts"}:
+                        continue
+                    text = safe_read(file_path)
+                    skip_lines = deny_block_lines(text)
+                    lines = text.splitlines()
+                    for marker in SUSPICIOUS_TEXT:
+                        hits = [idx for idx, line in enumerate(lines) if marker in line]
+                        if any(idx not in skip_lines for idx in hits):
+                            suspicious.append({
+                                "path": str(file_path.relative_to(root)),
+                                "marker": marker,
+                                "category": category,
+                            })
+        surfaces[category] = found
+
+    result["surfaces"] = surfaces
+    result["suspicious_markers"] = suspicious
+
+    if args.json:
+        print(json.dumps(result, indent=2, sort_keys=True))
+    else:
+        print(f"Repo root: {root}")
+        print("\nActive-looking surfaces:")
+        for category, paths in surfaces.items():
+            if paths:
+                print(f"- {category}: {', '.join(paths)}")
+        if suspicious:
+            print("\nSuspicious markers needing review:")
+            for item in suspicious:
+                print(f"- {item['path']} [{item['category']}]: {item['marker']}")
+        else:
+            print("\nNo built-in suspicious markers found by probe. Run AgentShield for full analysis.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.grok/skills/autoresearch-coding/README.md

@@ -0,0 +1,15 @@
+# Autoresearch Coding
+
+Metric-driven improvement loop for AI coding agents.
+
+Example:
+
+```text
+/autoresearch-coding goal: improve API latency; metric command: npm run bench; direction: lower; editable paths: src/api src/lib; protected paths: .env* migrations; budget: 5
+```
+
+For this kit:
+
+```text
+/autoresearch-coding goal: improve the kit; metric command: node .vibekit/scripts/validate-kit.mjs .; direction: higher; editable paths: .vibekit/docs .vibekit/scripts .vibekit/skills .vibekit/commands .claude .cursor .agents .codex-plugin; budget: 3
+```

package/.grok/skills/autoresearch-coding/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: autoresearch-coding
+description: Run a metric-driven coding experiment loop. Use when improving a repo through repeated hypotheses, benchmark-guided changes, validation, keep/discard decisions, or safe workflow enhancement. Requires a goal, metric command, direction, editable paths, protected paths, and budget.
+disable-model-invocation: true
+argument-hint: goal; metric command; direction; editable paths; protected paths; budget; timeout
+---
+
+# Autoresearch Coding Loop
+
+Run a controlled experiment loop. Do not perform open-ended destructive work.
+
+## Contract
+
+Extract or infer:
+
+- Goal.
+- Metric command.
+- Direction: `lower` or `higher` is better.
+- Editable paths.
+- Protected paths.
+- Budget, default 3.
+- Timeout, default 10 minutes.
+
+If the metric command or editable scope is missing, infer conservative defaults and show the contract before editing. If no safe metric exists, ask for one.
+Always print the resolved contract before the baseline run, and label inferred fields.
+
+For this kit itself, use:
+
+```text
+goal: improve Minimal Vibe Coding Kit quality
+metric command: node .vibekit/scripts/validate-kit.mjs .
+direction: higher
+editable paths: .vibekit/docs .vibekit/scripts .vibekit/skills .vibekit/commands .claude .cursor .agents .codex-plugin .github README.md AGENTS.md .vibekit/init/CLAUDE-template.md .vibekit/init/FIRST_TIME_INIT.md .vibekit/init/FIRST_PROMPT.md backbone.yml package.json install.sh install.ps1
+protected paths: .git .env* node_modules vendor secrets lockfiles
+budget: 3
+```
+
+## Setup
+
+1. Read `backbone.yml`. If `meta.template_status` is `uninitialized`, follow `.vibekit/init/FIRST_TIME_INIT.md` and wait for explicit approval before experiment edits.
+2. Inspect `git status --short`.
+3. If user changes exist, stop unless the user permits dirty-state experimentation.
+4. Create or switch to an experiment branch named `autoresearch/<date>-<slug>` when a git repo is available. If branch creation is blocked by permissions, ask for approval once and record any approved fallback.
+5. Create local-only paths if missing:
+   - `.autoresearch/logs/`
+   - `.autoresearch/notes/`
+   - `results.tsv`
+6. Initialize `results.tsv` with:
+
+```text
+commit	metric_value	direction	status	seconds	log_path	description
+```
+
+Do not commit `.autoresearch/` or `results.tsv` unless the user asks.
+
+## Baseline
+
+Before edits:
+
+1. Run the metric command once.
+2. Save output to `.autoresearch/logs/baseline.log`.
+3. Extract a metric value using `references/metric-extraction.md`. If ambiguous, use pass/fail plus warning count and explain.
+4. Append a baseline row with status `keep`.
+
+## Experiment loop
+
+For each experiment:
+
+1. Read the best kept result from `results.tsv`.
+2. Form one small hypothesis.
+3. Modify only editable paths.
+4. Run the metric command with timeout and log output.
+5. Decide:
+   - `keep`: metric improves, or equal metric with simpler safer code.
+   - `discard`: worse or equal without simplification.
+   - `crash`: command fails, times out, or no usable metric.
+6. Append a row to `results.tsv`.
+7. Keep good changes; revert discarded or crashed changes.
+8. If a crash is from a trivial patch mistake, fix once and rerun.
+
+If a kept change touches agent surfaces such as `AGENTS.md`, `CLAUDE.md`, `.claude/**`, `.cursor/**`, `.agents/**`, `.codex-plugin/**`, `.vibekit/skills/**`, `.vibekit/commands/**`, `.vibekit/scripts/**`, hooks, or MCP config, run the AgentShield probe before final reporting.
+
+## Delegation
+
+Use subagents when available:
+
+- `hypothesis-planner`: next experiment idea.
+- `implementation-hacker`: apply scoped patch.
+- `test-runner`: run noisy commands and return metrics.
+- `debug-fixer`: fix trivial crash bugs.
+- `code-reviewer`: review kept changes.
+- `results-analyst`: summarize ledger.
+- `security-reviewer`: review agent-surface changes.
+
+## Stop
+
+Stop when budget is reached, metric is missing, protected paths are needed, three unrelated crashes happen, or the user changes the goal.
+
+## Final report
+
+Report baseline, best metric, kept/discarded/crashed counts, changed files, validation output, security probe result when relevant, risks, and log locations.

package/.grok/skills/autoresearch-coding/references/experiment-contract.md

@@ -0,0 +1,13 @@
+# Experiment contract
+
+Required fields:
+
+- Goal
+- Metric command
+- Direction: lower or higher
+- Editable paths
+- Protected paths
+- Budget
+- Timeout
+
+The agent must print the contract before editing. If any field is inferred, label it `inferred`.

package/.grok/skills/autoresearch-coding/references/metric-extraction.md

@@ -0,0 +1,8 @@
+# Metric extraction
+
+Prefer a numeric metric from the command output. If the command only returns pass/fail, score it as:
+
+- pass: 1
+- fail: 0
+
+When warnings matter, report pass/fail plus warning count. Do not hide failures behind a single score.

package/.grok/skills/autoresearch-coding/references/result-ledger.md

@@ -0,0 +1,15 @@
+# Result ledger
+
+Use `results.tsv` with this header:
+
+```text
+commit	metric_value	direction	status	seconds	log_path	description
+```
+
+Status values:
+
+- `keep`
+- `discard`
+- `crash`
+
+Keep verbose command output in `.autoresearch/logs/`.

package/.grok/skills/autoresearch-coding/scripts/log_result.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+import argparse
+from pathlib import Path
+
+HEADER = "commit\tmetric_value\tdirection\tstatus\tseconds\tlog_path\tdescription\n"
+
+parser = argparse.ArgumentParser(description="Append an autoresearch result row")
+parser.add_argument("--file", default="results.tsv")
+parser.add_argument("--commit", required=True)
+parser.add_argument("--metric", required=True)
+parser.add_argument("--direction", required=True, choices=["lower", "higher"])
+parser.add_argument("--status", required=True, choices=["keep", "discard", "crash"])
+parser.add_argument("--seconds", required=True)
+parser.add_argument("--log", required=True)
+parser.add_argument("--description", required=True)
+args = parser.parse_args()
+
+path = Path(args.file)
+if not path.exists():
+    path.write_text(HEADER, encoding="utf-8")
+row = "\t".join([args.commit, args.metric, args.direction, args.status, args.seconds, args.log, args.description.replace("\t", " ")]) + "\n"
+with path.open("a", encoding="utf-8") as f:
+    f.write(row)
+print(f"logged {args.status} -> {path}")

package/.grok/skills/autoresearch-coding/scripts/run_logged.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+import argparse
+import subprocess
+import time
+from pathlib import Path
+
+parser = argparse.ArgumentParser(description="Run a command with timeout and log output")
+parser.add_argument("command", help="Shell command to run")
+parser.add_argument("--log", required=True, help="Log path")
+parser.add_argument("--timeout", type=int, default=600)
+args = parser.parse_args()
+
+log = Path(args.log)
+log.parent.mkdir(parents=True, exist_ok=True)
+start = time.time()
+try:
+    result = subprocess.run(args.command, shell=True, text=True, capture_output=True, timeout=args.timeout)
+    seconds = time.time() - start
+    log.write_text(result.stdout + result.stderr, encoding="utf-8", errors="ignore")
+    print(f"exit_code={result.returncode}")
+    print(f"seconds={seconds:.3f}")
+    print(f"log={log}")
+    raise SystemExit(result.returncode)
+except subprocess.TimeoutExpired as exc:
+    seconds = time.time() - start
+    log.write_text((exc.stdout or "") + (exc.stderr or "") + f"\nTIMEOUT after {args.timeout}s\n", encoding="utf-8", errors="ignore")
+    print("exit_code=124")
+    print(f"seconds={seconds:.3f}")
+    print(f"log={log}")
+    raise SystemExit(124)

package/.grok/skills/clearthought/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: clearthought
+description: Structured reasoning for complex coding work. Use when requirements are ambiguous, a design/debugging decision has multiple valid paths, or a large request needs to be split into safe implementable tasks.
+argument-hint: "[operation] <problem>"
+user-invocable: true
+effort: high
+---
+
+# ClearThought
+
+Use ClearThought to turn complex or ambiguous coding work into an evidence-based implementation plan.
+
+## Best Use
+
+Use this skill when:
+
+- requirements are broad, conflicting, or under-specified;
+- a bug needs root-cause analysis before editing;
+- an architecture or refactor decision has tradeoffs;
+- a task needs to be split into small pull-request sized steps;
+- the user asks for deliberate reasoning, ClearThought, or a structured decision.
+
+## Operations
+
+Choose the narrowest operation that fits:
+
+- `sequential_thinking`: decompose a complex request into ordered work.
+- `debugging_approach`: isolate a broken behavior with hypotheses and checks.
+- `decision_framework`: compare implementation options and choose one.
+- `systems_thinking`: map components, contracts, and side effects.
+- `scientific_method`: define hypothesis, metric, baseline, experiment, and result.
+- `risk_review`: identify safety, security, data, and rollback risks.
+- `implementation_plan`: produce an edit plan, validation plan, and review checklist.
+
+If the operation is omitted, infer it from the request. Default to `sequential_thinking`.
+
+## Workflow
+
+1. Read `AGENTS.md` and `backbone.yml` before repo edits.
+2. Separate observed facts, assumptions, unknowns, and decisions.
+3. Pick one operation and keep the reasoning focused on the next useful action.
+4. Split the work into safe tasks with file or module ownership where possible.
+5. Define validation commands and risk checks before editing.
+6. Revisit the plan when new evidence invalidates an assumption.
+
+## Output
+
+For normal coding work, return this concise structure:
+
+```markdown
+## ClearThought Brief
+
+Operation: <operation>
+Problem: <one sentence>
+Observed facts:
+- <facts from files, tests, logs, or user request>
+Assumptions:
+- <explicit assumptions>
+Plan:
+1. <small implementable step>
+2. <small implementable step>
+Validation:
+- <commands or checks>
+Risks:
+- <risk and mitigation>
+```
+
+For user-invoked JSON mode, return valid JSON:
+
+```json
+{
+  "toolOperation": "operation_name",
+  "problem": "brief problem statement",
+  "observedFacts": [],
+  "assumptions": [],
+  "plan": [],
+  "validation": [],
+  "risks": [],
+  "sessionContext": {
+    "sessionId": "conversation"
+  }
+}
+```
+
+## References And Examples
+
+Load these only when the active task needs more detail:
+
+- `references/parameter-reference.md`: operation parameters and accepted values.
+- `references/output-schemas.md`: JSON response shapes for supported operations.
+- `examples/sequential-thinking.md`: decomposition and step-by-step planning examples.
+- `examples/decision-framework.md`: option comparison and tradeoff examples.
+- `examples/metagame-examples.md`: OODA, Ulysses, and high-stakes reasoning examples.
+
+## Safety
+
+- Do not expose long hidden reasoning. Provide concise rationale and actionable conclusions.
+- Do not invent facts. Mark weak evidence as an assumption or unknown.
+- Do not run package lifecycle scripts, hooks, deploys, migrations, or destructive commands just to think.
+- Prefer reversible changes and small diffs when uncertainty is high.