What It Installs, Tool by Tool

Where we are: "How We Use This Repo" walked through running the install — bun .../install.ts, cp -R, or aidlc config, depending on what we have. This page is about the result: what actually shows up in a project afterward.

In plain English: After you run the install, two new things appear in your project folder: a shared notebook (the aidlc/ workspace — plain files that record everything the AI decided and why) and a tool-specific adapter (the "engine folder" — files that teach your specific harness, like Claude Code or Cursor, how to read that notebook). The notebook is what actually matters and gets saved to git; the adapter is just plumbing.

The Big Picture

flowchart TB
    CORE["core/<br/>the engine"] --> PKG(("bun scripts/package.ts"))
    HARN["harness/&lt;name&gt;/<br/>tool adapter"] --> PKG
    PKG --> DIST["dist/&lt;harness&gt;/"]
    DIST -->|"install.ts, cp -R,<br/>or aidlc config"| ENGINE

    subgraph PROJECT["your-project/"]
        ENGINE[".cursor/ · .claude/ · .kiro/ ..."]
        ONB["AGENTS.md / CLAUDE.md"]
        WS["aidlc/<br/>the workspace"]
        ENGINE -. reads / writes .-> WS
    end

The engine folder is generated and disposable — regenerate it any time by re-running the install. The aidlc/ workspace next to it is the real, permanent record.

The aidlc/ Workspace

In plain English: This is one folder, aidlc/, split into four sub-folders. Think of it like a project binder with four tabbed sections: the rulebook, the reference material, a map of the code, and a diary of every decision made.

flowchart LR
    SPACE["spaces/default/"] --> MEM["memory/<br/>THE METHOD"]
    SPACE --> KNOW["knowledge/<br/>DOMAIN KNOWLEDGE"]
    SPACE --> CODE["codekb/<br/>CODE KNOWLEDGE"]
    SPACE --> INT["intents/<br/>THE RECORD"]

All of it is committed (saved to git, so your team shares it), except two per-user cursors (active-space, active-intent) and a little machine-local scratch — those stay private to your own machine, the same way an editor remembers your cursor position without saving it to the file.

AGENTS.md vs. CLAUDE.md

Same file, same shared template — just a different name per tool, because that's the filename each harness looks for automatically when it opens a project.

Per-Tool Summary

What's an "MCP server"? A small local program that gives your AI harness a new ability — like letting it query a database or call an API — beyond just reading and writing files. You don't need to understand it deeply to use this tool; just know it's an optional extra some harnesses ship with.

Two Patterns

flowchart TB
    subgraph Visible["Visible — Claude · Cursor · Kiro · Codex"]
        VE["Full engine sits in one dot-folder<br/>your tool reads straight from it"]
    end
    subgraph Hidden["Hidden — Copilot · opencode"]
        HE[".aidlc/ — full engine, never scanned by the tool"]
        HV[".github/ or .opencode/ — a few pointer files"]
        HV -->|points at| HE
    end

Some tools (Copilot, opencode) only look inside their own specific folder, not a generic .aidlc/ one — so for those, the full engine hides in .aidlc/ and a handful of small "pointer" files sit in the folder that tool does check, directing it there.

Every harness still ships the same three ingredients — just visible or tucked away:

1. 14 agent personas + 1 orchestrator skill — think of these as 14 specialist "hats" the AI can put on (architect, tester, security reviewer, and so on), plus one conductor that decides which hat is needed next.
2. Hook wiring — small scripts that run automatically at the right moment (e.g., "log this decision" every time a file is saved).
3. The engine itself — tools/, knowledge/, sensors/, scopes/

‹ Back to: How We Use This Repo Continue to: Repo Architecture, Explained