| title | description | keywords | author | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
StartVibe: Bootstrap AI‑Ready Repos with Documentation‑Driven and Behavior‑Driven Development |
Turn any repository into an AI‑readable workspace in seconds. Start curious, shape the idea, and ship a CLI that scaffolds /.ai docs, Copilot instructions, and BDD‑ready workflows. |
|
egyjs |
Start curious. Let your thoughts wander until a spark hits — that "what if?" moment. What if a repo could explain itself to an AI the way we explain ideas to teammates? What if documentation wasn’t a chore but the engine? Shape it into a concept, refine it into a workflow, and then build the tool that brings it to life.
That tool is StartVibe.
A tiny CLI that turns any repository into an AI‑ready, docs‑first, BDD‑friendly workspace — with one command.
- StartVibe installs an AI‑native scaffolding into your repo:
/.aidocs, Copilot instructions, and feature specs. - You write intent in Markdown. Agents (and humans) turn it into tests and code.
- Works with any language; encourages BDD with your native test framework.
- One command to get started:
npx start-vibe- Why this, why now?
- The concept: Vibe Coding
- Core principles
- The /.ai workspace (source of truth)
- From docs → tests → code
- The CLI: start-vibe
- Templates overview
- Language and BDD framework mapping
- Example feature flow
- Roadmap and extensions
- FAQ
- What I built
Modern codebases aren’t just for humans anymore — they’re read by AI copilots, CI bots, and automation. Yet most repos still bury intent in issues or chats. Developers guess; AIs hallucinate. Slow velocity, uneven quality.
StartVibe flips the default: make intent explicit, structured, and close to the code. Give both humans and machines a shared, living source of truth.
Benefits you feel immediately:
- Faster onboarding (for humans and AI tools)
- Clearer changes because the “why” lives alongside the “what”
- Smoother BDD/TDD loops — specs become tests, tests shape code
- Fewer miscommunications, fewer surprises
Vibe Coding is a simple idea:
- Describe behavior in plain language.
- Let agents (and humans) translate that intent into tests.
- Make the code satisfy those tests.
Documentation‑Driven Development (DDD) + Behavior‑Driven Development (BDD) + AI‑assisted iteration. The “vibe” is your repo’s personality — the guardrails that help agents act like great collaborators.
- Documentation as source of truth — Markdown first, code follows.
- Behavior over implementation — focus on “When X, expect Y.”
- AI‑readable by design — consistent structure, clear context, minimal ambiguity.
- Framework‑agnostic — use your language’s native test tools.
- Non‑destructive — lives in
/.ai; your app code stays your app code.
StartVibe installs a dedicated, discoverable knowledge space. It’s small, opinionated, and practical:
.ai/
ARCHITECTURE.md # System design, components, data flow
CONVENTIONS.md # Coding patterns, naming, style
TICKETS.md # Priorities, backlog, task tracker
ci_cd_instructions.md # How to build, test, and deploy
features/
example_feature_login.md # BDD-style feature spec(s)
.github/
copilot-instructions.md # IDE assistant guidance
Why a separate folder? Two reasons:
- Keep intent separated from implementation — clean mental model.
- Give AI tools a single, predictable entry point.
The loop looks like this:
- Author feature specs in
/.ai/features/*.mdusing Given/When/Then. - Generate native tests (Jest, Pest, RSpec, etc.).
- Implement code until tests pass. Repeat.
This respects your stack while making the intent crisp and machine‑consumable.
StartVibe is a zero‑config bootstrapper. It drops the AI‑ready docs into your current repo without touching your application code.
- Install via NPX (no global install required):
npx start-vibe- Key flags:
--force— overwrite existing files--dry-run— show what would be created--silent— suppress logs--verbose— detailed progress
The CLI copies the templates and prompts before overwriting (defaults to Yes with a batch mode when desired). It’s fast, friendly, and gets out of your way.
You’ll get thoughtfully structured starter files, each with a purpose:
/.ai/ARCHITECTURE.md— system design and component boundaries/.ai/CONVENTIONS.md— coding patterns and style/.ai/TICKETS.md— task tracking and priorities/.ai/ci_cd_instructions.md— build, test, deploy guidance/.ai/features/*.md— behavior specs (Given/When/Then)/.github/copilot-instructions.md— tuned hints for IDE assistants
These are starting points, not rules. Customize them to your team’s voice and needs.
StartVibe avoids lock‑in. Write specs in Markdown; generate tests in your ecosystem:
- PHP → Pest
- JavaScript/TypeScript → Jest
- Python → Behave / pytest‑bdd
- Java → Cucumber‑JVM
- Ruby → RSpec
- C# → SpecFlow
- Go → Ginkgo
- Swift → Quick
Generated tests belong in your project — not under /.ai — so they run in your normal CI.
- Create a feature spec:
# 2025-11-01_feature_user_login.md
Feature: User Login
As a registered user
I want to log in securely
So that I can access my account
Scenario: Valid credentials
Given a registered user with email "[email protected]"
When they submit valid credentials
Then they are redirected to their dashboard
And a session cookie is set- Generate tests in your stack (manually or via an agent).
- Implement the feature until tests pass.
- Commit: docs, tests, code — the trifecta.
- Language/framework detection to auto‑suggest test libraries
- Generator that translates
/.ai/features/*.mdinto native tests - GitHub Action to validate features on PR
- Richer agent recipes in
/.ai/agents.md - Optional
/.ai/history/to capture decisions and iterations
Is this only for AI? No — humans benefit first: clearer intent, faster onboarding, better commit narratives.
Will it rewrite my code? No. StartVibe only adds documentation and guidance files. Tests and implementation remain in your app folders.
Can I use it in any repo? Yes. It’s framework‑agnostic and non‑destructive.
Is this BDD‑only? It encourages BDD because it pairs well with AI assistance, but you can adapt the flow to your style.
I packaged the idea into a real tool you can use today:
- GitHub: https://github.com/egyjs/StartVibe
- Run it now:
npx start-vibeGive your codebase a vibe — and let AI understand it.