{
"markdown": "\n\n# Knowledge & Vibes\n\n### A framework for building software with AI\n\n[](https://opensource.org/licenses/MIT)\n[](./research/README.md)\n\n
\n\n---\n\n## What This Is\n\nA structured workflow for building real software with AI assistance. Plans are explicit, work is tracked, and verification is mandatory.\n\nThe core insight: **truth lives outside the model.** The AI's confident output is not truth. Truth is tests that pass, code that compiles, documentation that exists. Everything else is a hypothesis that needs verification.\n\n---\n\n## The Toolstack\n\nSix open-source CLI tools that give AI agents structure, memory, and accountability. Together they enable multiple agents to work on the same codebase without conflicts, remember what worked across sessions, and catch bugs before they ship.\n\n| Tool | What It Does | Repo |\n|:-----|:-------------|:-----|\n| [**bd**](https://github.com/Dicklesworthstone/mcp_agent_mail) | Track tasks with dependencies and verification gates | mcp_agent_mail |\n| [**bv**](https://github.com/Dicklesworthstone/mcp_agent_mail) | Analyze task graph—blockers, critical path, what's ready | mcp_agent_mail |\n| [**Agent Mail**](https://github.com/Dicklesworthstone/mcp_agent_mail) | Coordinate agents—file reservations, messaging, handoffs | mcp_agent_mail |\n| [**ubs**](https://github.com/Dicklesworthstone/ultimate_bug_scanner) | Scan for security vulnerabilities before every commit | ultimate_bug_scanner |\n| [**cass**](https://github.com/Dicklesworthstone/coding_agent_session_search) | Search past sessions—find how you solved it before | coding_agent_session_search |\n| [**cm**](https://github.com/Dicklesworthstone/cass_memory_system) | Persist learned patterns and rules across sessions | cass_memory_system |\n\n> **Quick install:** Each tool installs with a single `curl | bash` command.\n> See the [Setup Guide](./docs/guides/SETUP_GUIDE.md) for details.\n\n---\n\n## The Problem It Solves\n\nAI-assisted development fails in predictable ways:\n\n- **The AI builds the wrong thing** because goals weren't explicit\n- **Requirements vanish mid-project** because context windows have limits\n- **Multiple agents conflict** because there's no coordination protocol\n- **Bugs compound silently** because there are no verification gates\n- **\"It works\" isn't evidence** because confidence doesn't equal correctness\n\nYou can't prompt your way out of these problems. You need a system where failures get caught before they matter.\n\n---\n\n## How It Works\n\n### 0. Discover Thoroughly\n\nBefore the formal pipeline, surface every decision hiding in your idea. Use relentless curiosity to interrogate frontier models until nothing is left to interpret. **The plan is complete when any capable agent could implement without asking a single clarifying question.**\n\n> Plan as much as appropriate. Give the AI as few decisions as possible.\n\n### 1. Plan Explicitly\n\nBefore anyone writes code, the goal is pinned down. A North Star Card captures what success looks like, what's out of scope, and when the AI should stop and ask. Requirements are written in testable terms. Decisions are recorded so they're not relitigated.\n\n### 2. Track Everything\n\nWork is broken into **beads**: tasks with dependencies, status, and verification requirements. Nothing gets forgotten. Nothing falls through the cracks. The graph of work is explicit and queryable.\n\n### 3. Coordinate Agents\n\nWhen multiple AI agents work simultaneously, they need a protocol. File reservations prevent conflicts. Claim/close announcements tell everyone what's taken. Calibration checkpoints catch drift before it compounds.\n\n### 4. Verify Continuously\n\nTests are written before implementation (TDD). Security scans run before every commit. If something fails after three attempts, it gets decomposed or escalated rather than retried indefinitely.\n\n---\n\n## Full Workflow\n\n```mermaid\nflowchart TB\n START([Start]) --> S0\n\n subgraph PLAN[Planning]\n S0[North Star] --> S1[Requirements]\n S1 --> S2[QA Pass]\n S2 --> S3[Decisions]\n S3 --> S4[Spikes]\n S4 --> S5[Plan Pack]\n end\n\n subgraph DECOMP[Decomposition]\n S6[Phases] --> S7[Beads]\n end\n\n subgraph EXEC[Execution]\n COORD[Coordinate] --> TDD[Tests First]\n TDD --> IMPL[Implement]\n IMPL --> CHECK{Pass?}\n CHECK -->|no| RETRY{Try 3?}\n RETRY -->|yes| IMPL\n RETRY -->|no| SPLIT[Decompose]\n SPLIT --> TDD\n CHECK -->|yes| SEC[Security Scan]\n SEC --> NEXT{More beads?}\n NEXT -->|yes| TDD\n end\n\n subgraph CAL[Calibration]\n COV[Coverage] --> DRIFT[Drift Check]\n DRIFT --> RESOLVE[Test Resolution]\n RESOLVE --> GATE{Pass?}\n end\n\n subgraph REL[Release]\n VERIFY[Verify All] --> ACCEPT[Acceptance]\n ACCEPT --> SHIP([Ship])\n end\n\n S5 --> S6\n S7 --> COORD\n NEXT -->|no| COV\n GATE -->|yes| VERIFY\n GATE -->|no| S0\n```\n\n---\n\n## The Research Behind It\n\nEvery protocol is backed by research. 50+ papers distilled into actionable practices:\n\n- Why TDD produces better outcomes with AI\n- Why long context degrades reasoning\n- Why orchestrator-worker patterns outperform single agents\n- Why extended self-correction makes things worse\n- Why tests should adjudicate disagreements, not rhetoric\n\nSee the [Research summaries](./research/README.md) for the full collection.\n\n---\n\n## What's In This Repository\n\n| Section | What You'll Find |\n|:--------|:-----------------|\n| [**Discovery**](./docs/workflow/DISCOVERY.md) | Pre-pipeline: curiosity-driven architecture (start here for new projects) |\n| [**Setup Guide**](./docs/guides/SETUP_GUIDE.md) | How to install and configure the toolchain |\n| [**Pipeline Reference**](./docs/workflow/IDEATION_TO_PRODUCTION.md) | The complete 11-stage pipeline |\n| [**Protocols**](./docs/workflow/PROTOCOLS.md) | 19 repeatable procedures for common situations |\n| [**Templates**](./TEMPLATES.md) | North Star cards, requirements, ADRs, and more |\n| [**Glossary**](./GLOSSARY.md) | Every term defined |\n\nStart with [**START_HERE.md**](./START_HERE.md) for the recommended reading order.\n\n---\n\n## Quick Setup: Agent Prompt\n\nCopy this entire block and give it to an AI agent to fully set up Knowledge & Vibes in your project:\n\n\nClick to expand full setup prompt
\n\n---\n\n**Copy everything below this line:**\n\n---\n\n# Knowledge & Vibes Setup Task\n\n**Repository:** https://github.com/Mburdo/knowledge_and_vibes\n\nSet up the complete Knowledge & Vibes framework in this project. Follow every step precisely.\n\n## Step 1: Verify/Install Global Tools\n\nCheck if these tools exist. For any that are missing, install them.\n\nRun this to check:\n\n command -v bd && echo \"bd: installed\" || echo \"bd: MISSING\"\n command -v bv && echo \"bv: installed\" || echo \"bv: MISSING\"\n command -v ubs && echo \"ubs: installed\" || echo \"ubs: MISSING\"\n command -v cass && echo \"cass: installed\" || echo \"cass: MISSING\"\n command -v cm && echo \"cm: installed\" || echo \"cm: MISSING\"\n\nIf any are missing, install them:\n\n # Beads (bd, bv) and Agent Mail\n curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --dir \"$HOME/mcp_agent_mail\" --yes\n\n # CASS (session search)\n curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_session_search/main/install.sh | bash -s -- --easy-mode\n\n # UBS (security scanner)\n curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh | bash -s -- --easy-mode\n\n # cm (context memory) - detect architecture and install\n mkdir -p ~/.local/bin\n ARCH=$(uname -m); OS=$(uname -s)\n if [ \"$OS\" = \"Darwin\" ] && [ \"$ARCH\" = \"arm64\" ]; then\n curl -L https://github.com/Dicklesworthstone/cass_memory_system/releases/latest/download/cass-memory-macos-arm64 -o ~/.local/bin/cm\n elif [ \"$OS\" = \"Darwin\" ]; then\n curl -L https://github.com/Dicklesworthstone/cass_memory_system/releases/latest/download/cass-memory-macos-x64 -o ~/.local/bin/cm\n else\n curl -L https://github.com/Dicklesworthstone/cass_memory_system/releases/latest/download/cass-memory-linux-x64 -o ~/.local/bin/cm\n fi\n chmod +x ~/.local/bin/cm\n\n## Step 2: Initialize Claude Code\n\nRun Claude Code's built-in init to create the base `.claude/` folder:\n\n /init\n\nThis creates `.claude/CLAUDE.md` with project-specific instructions.\n\n## Step 3: Copy K&V Configuration\n\nClone K&V temporarily and copy everything needed:\n\n # Clone K&V repo\n git clone --depth 1 https://github.com/Mburdo/knowledge_and_vibes.git /tmp/kv-setup\n\n # Create PLAN directory\n mkdir -p PLAN\n\n # Copy all agent configuration\n cp -r /tmp/kv-setup/.claude/commands .claude/\n cp -r /tmp/kv-setup/.claude/rules .claude/\n cp -r /tmp/kv-setup/.claude/skills .claude/\n cp -r /tmp/kv-setup/.claude/templates .claude/\n\n # Copy AGENTS.md template\n cp /tmp/kv-setup/templates/AGENTS_TEMPLATE.md ./AGENTS.md\n\n # Copy planning templates into PLAN directory\n cp /tmp/kv-setup/templates/NORTH_STAR_CARD_TEMPLATE.md ./PLAN/00_north_star.md\n cp /tmp/kv-setup/templates/REQUIREMENTS_TEMPLATE.md ./PLAN/01_requirements.md\n cp /tmp/kv-setup/templates/REQUIREMENTS_QA_TEMPLATE.md ./PLAN/02_requirements_qa.md\n cp /tmp/kv-setup/templates/DECISIONS_ADRS_TEMPLATE.md ./PLAN/03_decisions.md\n cp /tmp/kv-setup/templates/RISKS_AND_SPIKES_TEMPLATE.md ./PLAN/04_risks_and_spikes.md\n cp /tmp/kv-setup/templates/TRACEABILITY_TEMPLATE.md ./PLAN/05_traceability.md\n\n # Clean up\n rm -rf /tmp/kv-setup\n\n## Step 4: Initialize Beads\n\n bd init\n\n## Step 5: Analyze This Project\n\nNow analyze the current project to understand:\n\n1. **Language/Framework**: What technologies are used? (check package.json, Cargo.toml, pyproject.toml, go.mod, etc.)\n2. **Directory Structure**: What are the key directories and what do they contain?\n3. **Existing Patterns**: Any coding conventions already established?\n4. **Build/Test Commands**: How does the project build and test?\n5. **Current State**: Is there existing code? Tests? Documentation?\n\nRead any existing README, CONTRIBUTING, or architecture docs.\n\n## Step 6: Customize AGENTS.md\n\nEdit AGENTS.md with project-specific information based on your analysis:\n\n- Replace placeholder project name with actual name\n- Fill in the actual tech stack (languages, frameworks, databases)\n- List key directories with their purposes\n- Add the real build and test commands\n- Note any coding conventions you observed\n- Add project-specific restrictions (what NOT to do)\n\n## Step 7: Create Initial Codemap (If Existing Code)\n\nIf the project has existing code, create `CODEMAPS/overview.md` with:\n\n- Stack summary\n- Directory structure with purposes\n- Key files and their responsibilities\n- Patterns to follow\n- Build/test/run commands\n\n## Step 8: Provide Recommendations\n\nBased on your analysis, give me specific recommendations:\n\n**If starting from scratch:**\n- Suggest creating a North Star Card first\n- Offer to help with discovery questions\n- Point to docs/workflow/DISCOVERY.md\n\n**If existing codebase:**\n- Identify areas that could benefit from better structure\n- Suggest creating beads for known TODOs or issues\n- Recommend running `ubs .` to find existing problems\n\n**First commands to try:**\n- `/prime` - Start a working session\n- `bd create \"First task\" -t task -p 2` - Create first task\n- `bv --robot-triage` - Analyze task graph\n\n## Step 9: Commit Setup\n\n git add .beads/ .claude/ AGENTS.md PLAN/\n git add CODEMAPS/ 2>/dev/null || true\n git commit -m \"Initialize Knowledge & Vibes framework\"\n\n## Step 10: Present System Overview to User\n\nGenerate a personalized orientation for the human user. Use this structure:\n\n---\n\n# Knowledge & Vibes is Ready\n\n**Setup complete.** Here's what you now have and how to use it.\n\n## What Got Installed\n\n[List tools: what was already present vs newly installed, any issues]\n\n## Your New Toolchain\n\n```mermaid\nflowchart LR\n subgraph TOOLS[\"Your Tools\"]\n BD[\"bd\"]\n BV[\"bv\"]\n UBS[\"ubs\"]\n CASS[\"cass\"]\n CM[\"cm\"]\n end\n\n BD --> TASKS[\"Track tasks\"]\n BV --> GRAPH[\"See dependencies\"]\n UBS --> SCAN[\"Catch bugs\"]\n CASS --> HISTORY[\"Search past work\"]\n CM --> MEMORY[\"Remember patterns\"]\n```\n\n**What each does:**\n- **bd** — Task tracking. Create tasks, mark them done, see what's ready.\n- **bv** — Task graph analysis. Shows blockers, suggests what to work on next.\n- **ubs** — Security scanner. Run before commits to catch vulnerabilities.\n- **cass** — Session search. Find how you solved something before.\n- **cm** — Pattern memory. Retrieves learned rules across sessions.\n\n## Your Project Structure\n\n```\n[Show actual structure created, annotated for this specific project]\n```\n\n## The Workflow\n\n```mermaid\nflowchart LR\n PLAN[\"Plan it\"] --> DECOMPOSE[\"Break it down\"]\n DECOMPOSE --> BUILD[\"Build it\"]\n BUILD --> VERIFY[\"Verify it\"]\n VERIFY --> SHIP[\"Ship it\"]\n```\n\n**In practice:**\n1. **Plan** — Fill out the templates in `PLAN/`. Start with the North Star.\n2. **Decompose** — Break work into beads (tasks) with `bd create`.\n3. **Build** — Write tests first, then implement. Scan with `ubs` before commits.\n4. **Verify** — Run `/calibrate` to check for drift. `/release` when ready to ship.\n\n## This Project\n\n[Personalized analysis:]\n- **What I found:** [tech stack, existing code, current state]\n- **Key insight:** [most important thing about this codebase]\n- **Watch out for:** [anything notable - missing tests, unusual patterns, etc.]\n\n## What To Do Now\n\n**If starting fresh:**\n1. Open `PLAN/00_north_star.md` and define what success looks like\n2. Fill out requirements in `PLAN/01_requirements.md`\n3. Create your first task: `bd create \"First task\" -t task`\n\n**If existing codebase:**\n1. Run `ubs .` to see current issues\n2. Create beads for known TODOs or bugs\n3. Start a session with `/prime`\n\n## Quick Reference\n\n| You want to... | Run this |\n|----------------|----------|\n| Start working | `/prime` |\n| See available tasks | `bd ready` |\n| Create a task | `bd create \"description\"` |\n| Finish a task | `bd close ` |\n| Check for bugs | `ubs .` |\n| Find past solutions | `cass search \"query\"` |\n\n## Learn More\n\n- Full pipeline: `docs/workflow/IDEATION_TO_PRODUCTION.md`\n- All protocols: `docs/workflow/PROTOCOLS.md`\n- Research behind it: `research/README.md`\n\n---\n\n \n\n---\n\n## About\n\nThis framework is the distillation of three years of building with AI, starting from zero.\n\nWhen GPT-3.5 launched, I was in high finance. I couldn't write a line of code. But I recognized immediately that AI was going to fundamentally change how things get built, and I wanted to be part of it.\n\nSo I went all in. Not with tutorials or bootcamps, but with a first principles approach: *What can these models actually do? Where do they fail? How do you extract every ounce of capability while catching the inevitable mistakes?*\n\nThe early days were rough. The models were weaker. The tooling didn't exist. Every technique had to be discovered through trial and error. But I stayed in it, learning, building, refining, session after session, project after project.\n\nThree years later, I'm shipping complex applications with real users and real revenue. Not because I became a traditional developer, but because I learned how to work *with* AI in a way that produces reliable results.\n\nThis framework is everything I've learned, systematized. The protocols that prevent the common failures. The tools that catch mistakes before they ship. The workflow that turns AI-assisted coding from a gamble into a repeatable process.\n\n**If you're technical, this will make you faster. If you're not, this is proof that you can build real things anyway.**\n\n---\n\n\n\n**[Follow my work →](https://x.com/YachtsmanCap)**\n\n[](https://x.com/YachtsmanCap)\n\nMIT License\n\n
\n",
"bytes": 16167,
"sha": "586ef94f33ba53a0b144bcd5271724dd1a66ace1508a022add15832b9cc048e0",
"repo_slug": "mburdo/knowledge_and_vibes",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/skl_mburdo_knowledge_and_vibes_testing_resol_b4833cd3/readme"
}