# Agent Architect Kit ↔ ThumbGate Bridge

**Status:** shipped 2026-04-21. Test-backed. CLI-automatable. Safe to recommend publicly.

## What this is

[agent-architect-kit](https://github.com/ultrathink-art/agent-architect-kit) by @ultrathink-art is a CLAUDE.md + agent-role template kit that persists learnings as per-role markdown files (`agents/state/memory/<role>.md`). They solve the setup layer. ThumbGate solves the runtime-enforcement layer — PreToolUse hooks that actually block known-bad tool calls instead of hoping the agent reads its memory file.

The two stacks are complementary. A team running architect-kit graduates to ThumbGate when their markdown memory grows past the ~80-line ceiling their own `memory-directive.md` enforces, or when they want their `operations` meta-agent to do more than edit instructions — actually prevent the failing action.

This bridge turns that graduation into a one-shot command.

## The bridge

### What it does

`scripts/integrations/architect-kit-memory-bridge.js` walks an architect-kit memory directory, parses each per-role `.md` file, and emits one ThumbGate feedback entry per qualifying line:

| architect-kit section | → ThumbGate signal | notes |
|---|---|---|
| `## Mistakes` | `down` with `whatWentWrong` | every entry becomes a thumbs-down lesson |
| `## Learnings` | `up` with `whatWorked` | every entry becomes a thumbs-up memory |
| `## Stakeholder Feedback` | `up`/`down` depending on keywords | "rejected", "broken", "wrong", "hate", etc. flip negative |
| `## Session Log` | skipped | too granular to be useful in a searchable lesson DB |

Every ingested entry is tagged `architect-kit`, `role:<name>`, and the source section, so imports are auditable and rollbackable.

### How to run it

**Dry-run first** (no writes, prints classification):

```bash
npm run integrations:architect-kit:import -- \
  --dir=/path/to/agents/state/memory \
  --dry-run --json
```

**Real import** (writes to ThumbGate feedback log):

```bash
npm run integrations:architect-kit:import -- \
  --dir=/path/to/agents/state/memory
```

**Single role** (e.g. import only `coder.md`):

```bash
npm run integrations:architect-kit:import -- \
  --dir=/path/to/agents/state/memory \
  --role=coder
```

### What you get after import

```bash
npm run feedback:stats    # see new entries grouped by tag
npm run feedback:rules    # regenerate prevention rules from the imported mistakes
```

The imported mistakes now feed the same pipeline as native ThumbGate feedback: lesson DB indexing, Thompson Sampling rollups, prevention-rule generation, and PreToolUse hook injection. The architect-kit `operations` agent's "edit the instructions" loop is now backed by hooks that can actually refuse a tool call.

## Test proof

```bash
npm run test:architect-kit-memory-bridge
# 16 tests, 0 fail
```

Fixtures live in `tests/fixtures/architect-kit-memory/` and mirror the exact format from architect-kit's `memory-directive.md`. The test-suite parity guard (`tests/test-suite-parity.test.js`) pins this test into the `npm test` chain — dropping the test accidentally now fails CI.

## Positioning talking points (for outreach + docs)

- **CLAUDE.md is the control plane.** That's architect-kit's thesis and it's right. ThumbGate doesn't replace CLAUDE.md — it adds a runtime gate that enforces whatever CLAUDE.md says.
- **Template memory → queryable memory.** Per-role markdown files stop scaling past ~80 lines (architect-kit documents this limit themselves). ThumbGate's SQLite+FTS5+LanceDB store is what you migrate to when your memory deserves search.
- **Operations becomes teeth, not talk.** Their `operations` meta-agent edits instructions. ThumbGate lets operations also register prevention rules that PreToolUse hooks honor — the same loop, but the agent literally cannot skip it.

## What NOT to do

- **Do not re-import the same memory twice.** Architect-kit memory has no stable entry IDs; repeated imports duplicate lessons. Prune the source file (their own directive says to) before re-running, or run dry-run + diff first.
- **Do not import the `Session Log` section.** The bridge skips it deliberately. Session log entries are ephemeral task receipts, not lessons.
- **Do not assume operations-role edits propagate automatically.** The architect-kit operations agent edits markdown instruction files; ThumbGate's prevention rules are regenerated by `npm run feedback:rules`. Wire that into your Ralph Loop (or theirs) if you want continuous re-derivation.

## Files added/touched by this integration

- `scripts/integrations/architect-kit-memory-bridge.js` — parser + importer + CLI
- `tests/architect-kit-memory-bridge.test.js` — 16 unit tests
- `tests/fixtures/architect-kit-memory/{coder,qa}.md` — fixtures matching their format
- `package.json` — new `test:architect-kit-memory-bridge` and `integrations:architect-kit:import` scripts, chained into `npm test`
- `skills/agent-architect-kit/SKILL.md` — this doc

## When to reach back out to @ultrathink-art

If they ship stable entry IDs in their memory format, upgrade the bridge to do incremental imports (skip already-seen entries). Until then, treat this as a one-shot migration tool, not a sync daemon.