ai-engineering-cookbook

v0.1.1

Published

20 days ago

AI Engineering Cookbook — installable skills and hooks for Claude Code.

0High
0Medium
0Low

cloudbloqavi

AI Engineering Cookbook

Practical patterns, structures, and guidelines for building software autonomously with AI agents.

This cookbook provides an opinionated engineering workflow that combines Spec-Kit for planning ("what to build") and Superpowers for execution ("how to build it"), augmented with curated community extensions and an AI governance layer.

🤔 New Here? What Is AI-Native Engineering?

AI-Native Engineering is a development approach where AI agents write the majority of the code — but humans stay firmly in control by defining clear intent upfront and verifying outcomes rigorously.

Think of it this way: instead of writing code yourself, you write a precise specification of what the code should do. An AI agent then implements it, test by test, under strict constraints you set. Your role shifts from code author to intent definer and outcomes verifier.

This cookbook gives you the workflow, tools, and guardrails to do that safely and repeatably.

New to this? Follow the Learning Path below before diving into the guides. Don't know a term? Check the Glossary.

🎨 Interactive Cookbook Explorer

The AI Engineering Cookbook is accompanied by a modern, interactive web application that provides a comprehensive visual walkthrough of the entire agentic SDLC workflow, agent profiles, verification gates, and community extensions.

👉 Explore the Interactive Cookbook Explorer (hosted on GitHub Pages, or view the local code and guides)

🗺️ Visual SDLC Workflow

The diagram below shows how the workflow is split: Spec-Kit manages specification and planning, while Superpowers drives isolated test-driven implementation.

graph TD
    subgraph Spec-Kit Phase: What to Build
        A["1. Constitution (Rules)"] --> B["2. Specify (Idea)"]
        B --> C["3. Clarify (Q&A)"]
        C --> D["4. Plan (Architecture)"]
        D --> E["5. Tasks (Checklist)"]
    end

    E -->|tasks.md Handoff| F

    subgraph Superpowers Phase: How to Build
        F["6. Worktree Creation"] --> G["7. TDD Loop (RED/GREEN/REF)"]
        G --> H["8. Spec & Code Review"]
        H --> I["9. Final Verifications"]
        I --> J["10. Branch Finish / Merge"]
    end

🧰 Installable Skills

This repo ships portable Agent Skills (SKILL.md) you can drop into any compatible agentic tool — Claude Code, Cursor, Roo Code, VS Code Copilot, OpenAI Codex, Google Antigravity. The same skill file works everywhere; only the install folder differs.

Install any skill directly inside your target repository using npx:

# Install Doc Coherence
npx ai-engineering-cookbook doc-coherence

# Install Prompt Optimizer
npx ai-engineering-cookbook prompt-optimizer

(You can also run npx ai-engineering-cookbook without arguments for an interactive selection menu.)

🛠️ Troubleshooting & Installation Fallbacks

If the direct npx command fails or you are working in an environment with restricted network access/unresolved binary shims (common with direct GitHub URLs on Windows), choose one of these fallbacks:

Option A: Local DevDependency (Recommended)

Install the package locally to your target project. This ensures npm correctly configures binary shims on all operating systems:

# From npm registry:
npm install --save-dev ai-engineering-cookbook

# OR from GitHub directly:
npm install --save-dev github:cloudbloqavi/ai-engineering-cookbook

# Run the skill installer:
npx ai-engineering-cookbook doc-coherence

Option B: Global Installation

Install the CLI tool globally on your system:

# From npm registry:
npm install -g ai-engineering-cookbook

# OR from GitHub directly:
npm install -g github:cloudbloqavi/ai-engineering-cookbook

# Run the installer commands:
ai-engineering-cookbook doc-coherence
ai-engineering-cookbook prompt-optimizer

(Alternatively, you can run the direct script shortcuts: install-doc-coherence or install-prompt-optimizer.)

📚 Cookbook Documentation Directory

🛤️ Learning Path (Start Here)

Not sure where to begin? Follow this sequence:

💡 The Five Principles of AI-Native Engineering

In well-structured agentic pipelines, AI agents generate approximately 75% of the implementation code. This changes the human role from code author to intent definer, outcomes verifier, and system governor.

We enforce five core principles to manage this shift safely:

Intent First, Code Second: Code that passes tests but misses design intent is a liability. Clarify intent before generating.
Verify, Don't Just Generate: Value is measured by spec adherence, not lines produced. A smaller, correct implementation is always preferred.
Precision Over Productivity: Architectural consistency protects the codebase. Adhere to project guidelines even if they require extra steps.
Observability is Non-Negotiable: Every coding session must record reflections to feed the continuous learning loop.
Blameless Culture: Production bugs and gate escapes are system failures. We update spec-rules, check-gates, or prompt-skills to prevent them, rather than blaming the developer or agent.

📖 Glossary — canonical terms

To prevent the same concept being called different things across docs, these are the canonical names. Use them exactly; everything else points here.

🤝 Contributing

We welcome contributions! Read our Contributing Guide before submitting a PR — it covers branch naming, style guide, how to add new extensions, and the PR checklist.