minimal-vibe-coding-kit 0.3.0

package/.claude/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/.claude/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/.codex/README.md

@@ -0,0 +1,11 @@
+# Codex notes
+
+Codex reads `AGENTS.md` and repository skills from `.agents/skills`. This kit also includes `.codex-plugin/plugin.json` for plugin packaging.
+
+Useful built-ins in Codex CLI include `/init`, `/skills`, `/review`, `/permissions`, `/plan`, and `/goal` when available.
+
+Native custom reasoning skills:
+
+- `clearthought`: structured reasoning for broad or ambiguous coding tasks.
+- `sequential-thinking`: step-by-step task splitting with revisions and branches.
+- `reviewing-4p-priorities`: P0-P4 review triage and fix ordering.

package/.codex/config.example.toml

@@ -0,0 +1,8 @@
+# Example only. Copy to ~/.codex/config.toml if you want these defaults.
+project_doc_max_bytes = 65536
+project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]
+
+# Skills can be disabled by path if needed:
+# [[skills.config]]
+# path = "/absolute/path/to/.agents/skills/autoresearch-coding/SKILL.md"
+# enabled = false

package/.codex-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "minimal-vibe-coding-kit",
+  "version": "0.2.0",
+  "description": "Reusable vibe coding skills and workflows for Codex-compatible repositories.",
+  "author": {
+    "name": "Minimal Vibe Coding Kit"
+  },
+  "license": "MIT",
+  "skills": "./skills/"
+}

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

@@ -0,0 +1,11 @@
+# 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/.cursor/commands/council.md

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

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

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

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

@@ -0,0 +1,3 @@
+# 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/.cursor/commands/security-scan.md

@@ -0,0 +1,3 @@
+# 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/.cursor/commands/vibe-finalize.md

@@ -0,0 +1,3 @@
+# 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/.cursor/rules/001-vibe-core.mdc

@@ -0,0 +1,6 @@
+---
+description: Minimal Vibe Coding Kit core workflow for all Cursor agent tasks.
+alwaysApply: true
+---
+
+Read `backbone.yml` before changing code. If `meta.template_status` is `uninitialized`, follow `FIRST_TIME_INIT.md` and wait for approval before writing. After init, follow `backbone.yml` `conventions`. Keep diffs small, validate after relevant edits, and preserve user instructions outside managed blocks.

package/.cursor/rules/010-init.mdc

@@ -0,0 +1,7 @@
+---
+description: First-time init rules for Minimal Vibe Coding Kit.
+globs: ["backbone.yml", "FIRST_TIME_INIT.md", "CLAUDE.md", "AGENTS.md", ".cursor/rules/**"]
+alwaysApply: false
+---
+
+For init, print requirements first, detect stack and project conventions from files, propose one diff for `backbone.yml` plus rules, and wait for `yes`, `edit`, or `abort`. Do not overwrite existing `CLAUDE.md` or `AGENTS.md`.

package/.cursor/rules/020-security-agentshield.mdc

@@ -0,0 +1,7 @@
+---
+description: AgentShield security review for agent surfaces, skills, commands, hooks, MCP, and installer changes.
+globs: ["CLAUDE.md", "AGENTS.md", ".claude/**", ".cursor/**", ".agents/**", ".codex-plugin/**", "skills/**", ".vbkit-commands/**", ".vbkit-scripts/**", "hooks/**", ".mcp.json", "mcp.json"]
+alwaysApply: false
+---
+
+Run or ask to run `node .vbkit-scripts/agentshield-probe.mjs .` before merging agent-surface changes. Do not run untrusted hooks, MCP servers, deploys, migrations, or remote installers during review.

package/.cursor/rules/030-autoresearch-loop.mdc

@@ -0,0 +1,7 @@
+---
+description: Metric-driven autoresearch loop rules for repeated repo improvement.
+globs: ["src/**", "app/**", "lib/**", ".vbkit-docs/**", "skills/**", ".vbkit-scripts/**", ".vbkit-commands/**", ".claude/**", ".cursor/**", ".agents/**"]
+alwaysApply: false
+---
+
+Before repeated experiments, read `backbone.yml`; if it is uninitialized, complete the first-time init approval flow before experiment edits. Define goal, metric command, direction, editable paths, protected paths, budget, and timeout. Run a logged baseline before edits. Keep only improvements or safe simplifications. Run the AgentShield probe before the final report when kept changes touch agent surfaces.

package/.cursor/settings.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "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"
+  }
+}

package/.cursor/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.