tutor-buddy 🛡️

A Claude Code skill that takes vibecoders and beginners from a raw idea to a secured, GitHub-ready project — without the mistakes that usually follow.

AI-assisted coding makes it dangerously easy to commit a real API key, install a package an LLM hallucinated and an attacker then registered, build ten features before one works, or push code that a single malicious pull request can compromise. Tutor-buddy quietly prevents all of that — without adding ceremony or lecturing.

What it is

Tutor-buddy is not an application. It is a Claude Code skill: a set of Markdown instruction files that Claude Code loads and runs inside your project. There is no server, no runtime, no install-time build — just a workflow that executes on top of whatever you're building.

It runs a five-phase, gated workflow:

1. Ideate  →  2. Plan  →  3. Build  →  4. Security audit  →  5. Ship to GitHub

Each phase is a gate. Nothing moves forward without your explicit go-ahead.

How to install

Requirements: Claude Code with skills support.

1. Download tutor-buddy.skill from the Releases page.

2. Unzip it — it expands to a tutor-buddy/ folder.

3. Place it in a skills directory:

   # Global (all projects)
   mkdir -p ~/.claude/skills && mv tutor-buddy ~/.claude/skills/
   
   # Or project-only
   mkdir -p .claude/skills && mv tutor-buddy .claude/skills/
   

4. Restart Claude Code.

How to use

You don't call it by name — it activates from what you say. Just describe what you want:

I want to build a price-drop monitor that emails me alerts
I have no idea what to build — suggest something based on my background
Is this project safe to push to a public repo?
Help me put this on GitHub

You can enter at any phase. "I have an idea" starts at Phase 1; "is my project safe?" jumps straight to the audit; "put this on GitHub" goes to shipping.

When a decision is needed, tutor-buddy asks one question at a time with a sensible default. Reply "use the defaults" to keep moving.

The five phases

1 · Ideate — Bring your own idea or ask for one. Tutor-buddy stress-tests the scope, names the riskiest assumption, and pins down the smallest version worth building — before a line of code exists.

2 · Plan — Produces a written contract: full file/folder tree, boilerplate list, named and pinned dependencies, a .env.example, and a numbered build order.

3 · Build — Executes only the approved plan, milestone by milestone. Deviations are surfaced and approved, never silent. Secrets go in a gitignored .env from the start.

4 · Security audit — Runs automatically at the end of every build, and on demand. The core idea is honest results, not a checklist that creates false confidence. Threats are split into four groups by what an automated, build-time audit can actually verify:

Group A runs once per workspace in monorepos. A workspace that isn't inventoried is a workspace that never gets scanned — so the audit never emits a global PASS that hides an unscanned workspace; it reports it as an explicit gap.

5 · Ship — Creates the repo (private by default), enables push protection and secret scanning, configures branch protection against malicious PRs, and pins CI actions to commit SHAs.

What makes it different

Slopsquatting detection. Standard dependency audits check for known CVEs in packages that exist. They don't check whether a package was real to begin with. LLMs hallucinate plausible package names and attackers pre-register them — so tutor-buddy verifies every direct dependency resolves to a real, established package on its registry.

The plan is a contract. Requiring written plan approval before code addresses the most common vibecoding failure: scope expanding invisibly until the project is unshippable.

Honesty over reassurance. The audit states plainly what it cannot verify. A false green check is worse than no check — so human-factor threats are labelled NOT VERIFIABLE rather than rubber-stamped.

Token-economical. Locates before reading, reads only the relevant lines, batches questions with defaults, and never pastes full scanner logs back at you.

Repository layout

SKILL.md                       # Orchestrator: stance, token rules, phase routing, Phase 3
references/
  ideation.md                  # Phase 1
  planning.md                  # Phase 2
  security-audit.md            # Phase 4 (most of the security logic)
  github-setup.md              # Phase 5
tests/
  validate.py                  # Structural checks (reference + fixture integrity)
  fixtures/                    # Sample projects with documented expected audit results
.github/workflows/ci.yml       # Runs the structural checks on every push / PR

SKILL.md is an orchestrator, not the whole skill: each heavy phase's reference file is loaded only when that phase begins, keeping the active context small.

Development & testing

There's no application to unit-test — these checks guard the instructions.

# Reference integrity (every references/*.md cited in SKILL.md exists, and vice versa)
# plus fixture integrity (every fixture ships an EXPECTATIONS.md). Runs in CI.
python tests/validate.py

Audit fixtures under tests/fixtures/ are tiny sample projects, each exercising one Group A behavior with a documented EXPECTATIONS.md:

To validate a change to the skill, point a Claude Code session at a fixture, run the audit, and compare the report against that fixture's EXPECTATIONS.md. A mismatch is a regression. See tests/README.md for details.

Roadmap

• SBOM generation at the end of the build for a durable, portable dependency record.
• Deployment phase (Render, Railway, Vercel, Fly.io) with security-conscious defaults.
• Deeper slopsquatting heuristics — package age, maintainer reputation, name-similarity scoring, not just existence and download counts.
• More stacks — React Native / Expo, browser extensions, Tauri desktop apps.
• Configurable strictness — a lighter audit for prototypes, a stricter one for production-bound projects.

Contributing

Issues and PRs welcome — blunt, reasoned feedback preferred. If you find a security check that's missing, overclaiming, or wrong, open an issue with the reasoning. See Contributing.md for the bar a change has to clear.

License

MIT