minimal-vibe-coding-kit 0.3.0

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

@@ -0,0 +1,110 @@
+#!/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"],
+    "shared_skills": ["skills", ".agents/skills"],
+    "shared_commands": [".vbkit-commands"],
+    "kit_scripts": [".vbkit-scripts"],
+    "hooks": ["hooks", ".claude/hooks", ".agents/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 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)
+                    for marker in SUSPICIOUS_TEXT:
+                        if marker in text:
+                            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/.claude/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 .vbkit-scripts/validate-kit.mjs .; direction: higher; editable paths: .vbkit-docs .vbkit-scripts skills .vbkit-commands .claude .cursor .agents .codex-plugin; budget: 3
+```

package/.claude/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 .vbkit-scripts/validate-kit.mjs .
+direction: higher
+editable paths: .vbkit-docs .vbkit-scripts skills .vbkit-commands .claude .cursor .agents .codex-plugin .github README.md AGENTS.md CLAUDE-template.md FIRST_TIME_INIT.md 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 `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/**`, `skills/**`, `.vbkit-commands/**`, `.vbkit-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/.claude/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/.claude/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/.claude/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/.claude/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/.claude/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/.claude/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.