minimal-vibe-coding-kit 0.3.0

package/.agents/skills/visual-design-loop/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: visual-design-loop
+description: Run an iterative visual design improvement loop for UI/product polish tasks. Use when a request involves screenshots, rendering, visual review, frontend polish, layout/typography/color refinement, design QA, or a Claude/Codex loop goal that touches a visible product surface.
+---
+
+# Visual Design Loop
+
+Use this skill to improve a visible UI through controlled render-review-fix loops. Keep the brief and existing project conventions as the source of truth; do not add new product requirements just because a screen could be enhanced.
+
+## Contract
+
+Before editing, resolve and state:
+
+- Goal.
+- Target surface: route, page, component, flow, or supplied screenshot.
+- Source of truth: current brief plus repo instructions, design system, nearby UI, and `backbone.yml` when present.
+- Render method: local URL, app command, Storybook story, preview command, static file, or supplied screenshot.
+- Screenshot method: browser screenshot, Playwright, in-app browser, provided image, or equivalent.
+- Editable paths.
+- Protected paths.
+- Budget: default 3 loops.
+- Timeout: default 10 minutes per loop.
+- Log path: `/tmp/design-{project_slug}.md`.
+
+If render or screenshot capture is missing and cannot be inferred safely, ask for the missing command, URL, or image before editing.
+
+## Baseline
+
+1. Render the target surface.
+2. Capture or inspect the baseline screenshot.
+3. Review visible issues only; do not invent findings.
+4. Create or update `/tmp/design-{project_slug}.md`.
+5. Log the baseline screenshot, visual score, main issues, and any render constraints.
+
+Derive `project_slug` from `backbone.yml` `project.name` when available; otherwise use the repository directory name.
+
+## Visual rubric
+
+Score screenshots from 1 to 5 using:
+
+- Visual hierarchy: primary content and action are obvious.
+- Layout and spacing: alignment, rhythm, density, whitespace.
+- Typography: scale, contrast, readability, consistency.
+- Color and contrast: accessible, intentional, not noisy.
+- Component consistency: matches nearby UI and design system.
+- Responsiveness: works at relevant viewport sizes.
+- Interaction states: hover, focus, disabled, empty, loading, and error states when relevant.
+- Product fit: improves the brief without adding unnecessary features.
+
+## Loop
+
+For each loop:
+
+1. Review the latest screenshot.
+2. Identify the highest-impact visual issue.
+3. Form one small hypothesis.
+4. Apply one targeted fix inside editable paths only.
+5. Render again.
+6. Capture the after screenshot.
+7. Compare before and after.
+8. Keep the change only if quality improves, or if quality is equal with simpler and safer implementation.
+9. Revert only your own loop changes if the result is worse.
+10. Run the repo validation command when code changed.
+11. Append the loop result to `/tmp/design-{project_slug}.md`.
+
+Each loop entry must include:
+
+- Loop number.
+- Screenshot reviewed.
+- Issue found.
+- Hypothesis.
+- Fix applied.
+- Before/after judgment.
+- Rubric score before.
+- Rubric score after.
+- Validation result.
+- Remaining concerns.
+- Stop/continue decision.
+
+## Stop criteria
+
+Stop when:
+
+- The design is polished enough for the brief.
+- The latest loop gives no meaningful improvement.
+- Further changes would be subjective or overworked.
+- Budget is reached.
+- Validation fails for a non-trivial reason.
+- A product or design decision is required from the user.
+- Render or screenshot tooling is unavailable.
+
+## Final report
+
+Report:
+
+- Baseline score.
+- Final score.
+- Screenshots reviewed.
+- Changes kept.
+- Changes discarded, if any.
+- Validation result.
+- Remaining risks or design decisions.
+- Log path.

package/.agents/skills/visual-design-loop/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Visual Design Loop"
+  short_description: "Iterative screenshot-based UI polish loop"
+  default_prompt: "Use $visual-design-loop to render, screenshot, review, and improve this UI until it is polished but not overworked."

package/.claude/agents/code-reviewer.md

@@ -0,0 +1,11 @@
+---
+name: code-reviewer
+description: Reviews kept changes for correctness, maintainability, security, and missing tests.
+tools: Read, Grep, Glob, Bash
+---
+
+# code-reviewer
+
+Review the diff. Flag risks by severity and propose small fixes.
+
+Always respect `backbone.yml`, editable paths, protected paths, and user approval requirements.

package/.claude/agents/context-architect.md

@@ -0,0 +1,11 @@
+---
+name: context-architect
+description: Keeps always-loaded context concise and moves procedures into skills or path-scoped rules.
+tools: Read, Grep, Glob, Edit, MultiEdit
+---
+
+# context-architect
+
+Reduce boilerplate. Keep root instructions short. Move long procedures to skills and docs.
+
+Always respect `backbone.yml`, editable paths, protected paths, and user approval requirements.

package/.claude/agents/debug-fixer.md

@@ -0,0 +1,11 @@
+---
+name: debug-fixer
+description: Fixes trivial crash bugs introduced by the current experiment.
+tools: Read, Edit, MultiEdit, Grep, Glob, Bash
+---
+
+# debug-fixer
+
+Inspect the last log lines. Fix only patch-caused mistakes. Rerun once.
+
+Always respect `backbone.yml`, editable paths, protected paths, and user approval requirements.

package/.claude/agents/hypothesis-planner.md

@@ -0,0 +1,11 @@
+---
+name: hypothesis-planner
+description: Generates small testable hypotheses from code, docs, validation output, and previous results.
+tools: Read, Grep, Glob
+---
+
+# hypothesis-planner
+
+Propose one small experiment at a time. Include expected metric impact and files to edit.
+
+Always respect `backbone.yml`, editable paths, protected paths, and user approval requirements.

package/.claude/agents/implementation-hacker.md

@@ -0,0 +1,11 @@
+---
+name: implementation-hacker
+description: Applies scoped implementation patches inside editable paths only.
+tools: Read, Edit, MultiEdit, Grep, Glob
+---
+
+# implementation-hacker
+
+Implement the selected hypothesis only. Avoid protected paths and large rewrites.
+
+Always respect `backbone.yml`, editable paths, protected paths, and user approval requirements.

package/.claude/agents/research-coordinator.md

@@ -0,0 +1,11 @@
+---
+name: research-coordinator
+description: Coordinates autoresearch loops, assigns subagents, tracks metric and budget.
+tools: Read, Grep, Glob, Bash
+---
+
+# research-coordinator
+
+Coordinate the loop. Keep the contract visible. Stop on missing metric, dirty state, protected paths, or budget exhaustion.
+
+Always respect `backbone.yml`, editable paths, protected paths, and user approval requirements.

package/.claude/agents/results-analyst.md

@@ -0,0 +1,11 @@
+---
+name: results-analyst
+description: Summarizes experiment ledger and recommends next high-value experiments.
+tools: Read, Grep, Glob
+---
+
+# results-analyst
+
+Read results.tsv and logs. Summarize baseline, best result, kept/discarded/crashed counts, and next ideas.
+
+Always respect `backbone.yml`, editable paths, protected paths, and user approval requirements.

package/.claude/agents/security-reviewer.md

@@ -0,0 +1,11 @@
+---
+name: security-reviewer
+description: Reviews AI agent surfaces with AgentShield workflow and manual checks.
+tools: Read, Grep, Glob, Bash
+---
+
+# security-reviewer
+
+Run read-only probe first. Label scanner-backed, manual-confirmed, and manual-suspected findings separately.
+
+Always respect `backbone.yml`, editable paths, protected paths, and user approval requirements.

package/.claude/agents/test-runner.md

@@ -0,0 +1,11 @@
+---
+name: test-runner
+description: Runs validation, tests, benchmarks, and summarizes metrics from logs.
+tools: Read, Bash
+---
+
+# test-runner
+
+Run the approved metric command with timeout. Return exit code, metric value, seconds, and log path.
+
+Always respect `backbone.yml`, editable paths, protected paths, and user approval requirements.

package/.claude/agents/workflow-curator.md

@@ -0,0 +1,11 @@
+---
+name: workflow-curator
+description: Improves rules, skills, workflows, and docs through propose-only daily updates.
+tools: Read, Grep, Glob, Bash, Edit, MultiEdit
+---
+
+# workflow-curator
+
+Run daily report and validation. Propose a diff. Wait for approval before writing.
+
+Always respect `backbone.yml`, editable paths, protected paths, and user approval requirements.

package/.claude/commands/autoresearch-coding.md

@@ -0,0 +1,15 @@
+---
+description: Use the `autoresearch-coding` skill. Require goal, metric command, direction, editable paths, protected paths, budget, and timeout.
+---
+
+# autoresearch-coding
+
+Use the `autoresearch-coding` skill.
+
+Before editing:
+
+- Read `backbone.yml`; if it is uninitialized, run the first-time init approval flow first.
+- Resolve and print goal, metric command, direction, editable paths, protected paths, budget, and timeout.
+- Run and log a baseline before the first experiment.
+- Keep only metric improvements or equal-metric simplifications.
+- Run the AgentShield probe before the final report when kept changes touch agent surfaces.

package/.claude/commands/council.md

@@ -0,0 +1,7 @@
+---
+description: Coordinate relevant agents: research-coordinator, security-reviewer, code-reviewer, and results-analyst. Return one merged plan and one validation summary.
+---
+
+# council
+
+Coordinate relevant agents: research-coordinator, security-reviewer, code-reviewer, and results-analyst. Return one merged plan and one validation summary.

package/.claude/commands/daily-enhance.md

@@ -0,0 +1,7 @@
+---
+description: Use the `daily-workflow-curator` skill. Generate a report and proposed diff. Do not write until the user approves.
+---
+
+# daily-enhance
+
+Use the `daily-workflow-curator` skill. Generate a report and proposed diff. Do not write until the user approves.

package/.claude/commands/init-vibe.md

@@ -0,0 +1,7 @@
+---
+description: Use the `vibekit-init` skill. Print requirements first, propose a diff, and wait for approval before writing.
+---
+
+# init-vibe
+
+Use the `vibekit-init` skill. Print requirements first, infer project conventions, propose a diff for `backbone.yml` plus rules, and wait for approval before writing.

package/.claude/commands/security-scan.md

@@ -0,0 +1,7 @@
+---
+description: Use the `agentshield-security-review` skill. Run read-only probe first, then AgentShield scan if available. Do not run hooks or MCP servers.
+---
+
+# security-scan
+
+Use the `agentshield-security-review` skill. Run read-only probe first, then AgentShield scan if available. Do not run hooks or MCP servers.

package/.claude/commands/vibe-finalize.md

@@ -0,0 +1,7 @@
+---
+description: Graduate the project after init — move one-time bootstrap files into _vibekit-cleanup/ for deletion. Reversible; refuses to run on the kit source repo.
+---
+
+# vibe-finalize
+
+Graduate this project once init and the first prompt are complete. Run `node .vbkit-scripts/vibekit-finalize.mjs . --propose` to preview, then `--write --yes` to move one-time bootstrap files (FIRST_TIME_INIT.md, FIRST_PROMPT.md, PUSH_TO_GITHUB.md, CLAUDE-template.md) into `_vibekit-cleanup/` for deletion. It refuses to run on the kit source repo and is reversible with `--restore --write`.

package/.claude/rules/autoresearch.md

@@ -0,0 +1,3 @@
+# Autoresearch rules
+
+Use `/autoresearch-coding` for repeated improvement loops. Read `backbone.yml` first; if it is uninitialized, complete the first-time init approval flow before experiment edits. Require goal, metric, direction, editable paths, protected paths, budget, and timeout. Run a logged baseline before editing and keep only metric-positive or simplification-positive changes. Run the AgentShield probe before the final report when kept changes touch agent surfaces.

package/.claude/rules/security.md

@@ -0,0 +1,3 @@
+# Security rules
+
+Run `/security-scan` for changes to agent surfaces, commands, hooks, MCP, skills, or installer scripts. Do not run untrusted hooks, MCP servers, deploys, migrations, or remote installers during review.

package/.claude/rules/tooling.md

@@ -0,0 +1,6 @@
+# Tooling rules
+
+- Claude skills live in `.claude/skills/<name>/SKILL.md`.
+- Shared canonical skills live in `skills/<name>/`.
+- Keep root `CLAUDE.md` concise; import `AGENTS.md` when possible.
+- Put path-specific guidance in `.claude/rules/` rather than the root file.

package/.claude/rules/vibe-core.md

@@ -0,0 +1,8 @@
+# Vibe core rules
+
+- Read `backbone.yml` first.
+- Follow `backbone.yml` `conventions` after init.
+- Keep plans short and diffs small.
+- Use skills for repeatable procedures.
+- Validate with the command in `backbone.yml` after relevant edits.
+- Do not overwrite user instructions; use managed blocks.

package/.claude/settings.json

@@ -0,0 +1,22 @@
+{
+  "permissions": {
+    "deny": [
+      "Bash(rm -rf:*)",
+      "Bash(rm:*)",
+      "Bash(git push:*)",
+      "Bash(git push --force:*)",
+      "Bash(git reset --hard:*)",
+      "Bash(curl *|*sh:*)",
+      "Bash(wget *|*sh:*)",
+      "Bash(npm publish:*)",
+      "Bash(npx * --yes:*)",
+      "Bash(migrate *)",
+      "Bash(docker compose up*)",
+      "Bash(docker-compose up*)"
+    ]
+  },
+  "skillOverrides": {
+    "autoresearch-coding": "user-invocable-only",
+    "vibekit-init": "user-invocable-only"
+  }
+}

package/.claude/skills/agentshield-security-review/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: agentshield-security-review
+description: repository-native security review workflow for Claude Code and Codex projects using the AgentShield concept. Use when auditing or hardening agent configuration, skills, prompts, hooks, MCP servers, permissions, slash commands, Codex plugin files, Claude plugin files, AGENTS.md, CLAUDE.md, or repository-level AI coding-agent surfaces. Prefer this skill before merging changes to .claude, .codex, .codex-plugin, .claude-plugin, .agents, skills, .vbkit-commands, .vbkit-scripts, hooks, mcp configs, or generated code that touches agent execution.
+---
+
+# AgentShield Security Review
+
+Use this skill to run an AgentShield-style review that is native to both Claude Code and Codex repositories. Treat the repo root as the source of truth, then inspect agent surfaces before normal code review.
+
+## Core rule
+
+Do not invent findings. Prefer deterministic scanner output when available, then add reviewer judgment separately. Clearly label each finding as `scanner-backed`, `manual-confirmed`, or `manual-suspected`.
+
+## Standard workflow
+
+1. Identify the repo root and active harness surfaces.
+2. Run `node .vbkit-scripts/agentshield-probe.mjs .` to inventory Claude, Codex, shared skills, hooks, MCP, commands, and repo instruction files.
+3. If Node/npm is available, run AgentShield from the repo root:
+   ```bash
+   npx ecc-agentshield scan --path . --format text
+   ```
+4. If JSON is needed for CI or automation, run:
+   ```bash
+   npx ecc-agentshield scan --path . --format json
+   ```
+5. If safe auto-fixes are requested, first summarize the proposed edits, then run:
+   ```bash
+   npx ecc-agentshield scan --path . --fix
+   ```
+6. Re-run the scan after fixes and report before/after score, severity counts, and changed files.
+7. If AgentShield is unavailable, perform the fallback manual review in `references/review-checklist.md`.
+
+## Harness-native layout
+
+Use a shared root skill where possible:
+
+- `skills/agentshield-security-review/SKILL.md` is the canonical workflow.
+- Claude Code may add a slash-command shim in `.vbkit-commands/security-scan.md` or `.claude/commands/security-scan.md`.
+- Codex should consume the same root `skills/` directory through `.codex-plugin/plugin.json` or the repo's native skill/plugin mechanism.
+- Do not duplicate divergent Claude and Codex skill bodies. Duplication causes drift.
+
+See `references/native-install.md` for copy-ready Claude and Codex snippets.
+
+## What to inspect
+
+Prioritize runtime-active files over examples and docs:
+
+1. `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`
+2. `.claude/settings.json`, `.claude/settings.local.json`, `.claude/agents/*.md`, `.claude/commands/*.md`
+3. `.codex/config.toml`, `.codex/`, `.codex-plugin/plugin.json`
+4. `.agents/`, `agents/`, `skills/`, `.vbkit-commands/`, `.vbkit-scripts/`, `hooks/`
+5. `.mcp.json`, `mcp.json`, `mcp-configs/*.json`
+6. installer scripts, CI workflows, package scripts, and generated plugin manifests
+
+## Output contract
+
+Return a concise report with:
+
+- Security grade/score if AgentShield provides one.
+- Commands run and whether the scan was `npx`, local, CI, or fallback-manual.
+- Active harness surfaces found.
+- Critical/high findings with exact paths, severity, confidence, exploit impact, and fix.
+- Medium/low findings grouped separately.
+- Safe auto-fix candidates versus manual-only changes.
+- Claude-native and Codex-native installation notes when the repo lacks one of them.
+- Final remediation order.
+
+Use `references/report-template.md` for the preferred report format.
+
+## Safety constraints
+
+- Never print full secrets. Show only the file path and key name or a redacted prefix/suffix.
+- Do not run untrusted hook scripts, MCP server commands, package scripts, or installer scripts just to inspect them.
+- Do not apply `--fix` without first stating the planned edit types.
+- Treat wildcard shell permissions, unpinned `npx`, shell-running MCP servers, prompt-injection instructions, and silent hook failures as high-risk until proven otherwise.

package/.claude/skills/agentshield-security-review/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: AgentShield Security Review
+  short_description: Audit Claude, Codex, skills, hooks, MCP, and agent config surfaces.
+  icon: shield
+  brand_color: "#334155"

package/.claude/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
+skills/agentshield-security-review/SKILL.md
+skills/agentshield-security-review/references/review-checklist.md
+skills/agentshield-security-review/references/report-template.md
+skills/agentshield-security-review/scripts/agentshield_repo_probe.py
+.vbkit-commands/security-scan.md
+.codex-plugin/plugin.json
+.claude-plugin/plugin.json
+```
+
+## Claude Code command shim
+
+Create `.vbkit-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 `skills/` directory. Exact schema may vary by Codex plugin version, so preserve the existing repo schema and ensure it references root skills rather than a copied skill body.
+
+Example intent:
+
+```json
+{
+  "name": "your-repo",
+  "version": "0.1.0",
+  "skills": "./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/**"
+      - "skills/**"
+      - ".vbkit-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/.claude/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, .vbkit-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/.claude/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.