Forem: dotori

The file was still there. That was the problem.

dotori — Tue, 31 Mar 2026 08:34:32 +0000

The failure mode nobody warns you about

When Claude Code deletes a file, you notice immediately. git restore, back in business.

The dangerous case is when it doesn't delete the file.

A config overwritten with empty values. A hooks.json that exists but is blank. A settings.local.json silently reset after an update. The file is present. The watcher sees nothing wrong. But your AI agent is now operating on broken context — and you won't know until the session goes sideways.

As one developer documented: Claude overwrote an existing config file with blank values — no backup, no warning. The file was still there. That's exactly what makes this kind of corruption harder to notice and harder to recover from than outright deletion.

This is the problem I built afd to solve.

See it in action

Three things happening in that GIF:

afd start — zero config, auto-detects your AI tool setup
A critical config gets deleted mid-session
Restored in 184ms — before the agent's next command runs

What afd actually does

afd (Autonomous Flow Daemon) is a background daemon that acts as an Immune System for your repo. It doesn't just watch for deletion — it validates file content on every change, and restores from a known-good snapshot in < 270ms.

[afd] 🛡️ hooks.json overwritten with empty values | 🩹 Self-healed in 184ms | Context preserved.

From the agent's perspective, nothing happened.

The S.E.A.M Cycle

Every file event flows through four stages:

Sense — Chokidar detects any unlink or change event (< 10ms)
Extract — Health checks validate content, not just existence (< 5ms)
Adapt — Matches symptom to stored antibody in SQLite WAL (< 1ms)
Mutate — RFC 6902 JSON-Patch restores to last known-good state (< 25ms)

Total: < 270ms. The design constraint was simple — finish before Claude Code's next tool call registers the damage.

The non-obvious problems it solves

Silent corruption is harder than deletion

Deletion is loud. Corruption is quiet. afd validates file content on every write — empty values, malformed JSON, blank hooks — not just file presence. The file being there isn't enough.

Double-Tap Heuristic

How does afd know if a deletion was intentional?

$ rm .claudeignore        # First tap → healed silently
$ rm .claudeignore        # Second tap within 30s → afd stands down
  [afd] 🫡 Antibody IMM-001 retired. Double-tap detected.

Three or more deletes in one second = git checkout burst, suppression paused entirely.

Antibodies stay current

Snapshots refresh on every valid change. Restores always reflect the latest healthy state — not a stale backup from session start.

`afd score` — value dashboard

│  Auto-healed  : 3 background events          │
│  Tokens saved : ~2.9K                        │
│  Time saved   : ~40 min                      │
│  Cost saved   : ~$0.01                       │

Localized in Korean and English. Run afd lang ko to switch.

One command

# No install needed
npx @dotoricode/afd start

# Or install globally
npm install -g @dotoricode/afd

Zero config. Auto-detects Claude Code, Cursor, Windsurf. Injects PreToolUse hooks silently. Published on npm as @dotoricode/afd v1.1.0.

What's next

The current model is reactive — detect damage, restore. I'm working on a Workflow Genome layer that fingerprints healthy config states proactively, so afd flags drift before it becomes corruption.

Less "immune response." More "immune memory."

GitHub: https://github.com/dotoricode/autonomous-flow-daemon | npx @dotoricode/afd start

If you've been hit by silent config corruption — not deletion, but quiet overwrites — I'd genuinely like to hear how it manifested.

I built a linter for AI project structure — because every project looked different

dotori — Sun, 29 Mar 2026 19:38:11 +0000

The problem nobody talks about

Here's a pattern I kept running into:

I'd start a new project with Claude Code, get into a flow, build something real — and then look at the folder structure a week later and wonder who made these decisions.

Start 10 projects with AI coding tools, and you'll get 10 different structures. One has CLAUDE.md, another doesn't. One has .claude/hooks.json, three others don't even have a .claude/ directory. Documentation lives in docs/ in one project and nowhere in the next.

Then a teammate joins and the first message is always: "Where's the config? Do we have hooks set up? Is there a plan document somewhere?"

The AI tools themselves suffer from this too. Claude Code works better when it has structured context — agent definitions, skill files, templates, policies. But there's no built-in way to check whether your project actually has all of that in place.

I wanted something like ESLint, but for project layout.

So I built bkit-doctor

bkit-doctor is a CLI that diagnoses your AI-assisted project structure and fixes what's missing — in one command.

npx bkit-doctor check

bkit-doctor v1.0.0

  Project Structure Check
  ────────────────────────────────────
  [PASS]  .claude/ directory
  [PASS]  CLAUDE.md
  [FAIL]  .claude/hooks.json
  [FAIL]  .claude/settings.local.json
  [WARN]  docs/01-plan/
  [WARN]  docs/02-design/
  [PASS]  docs/03-task/
  [PASS]  docs/04-report/
  [FAIL]  Agent definitions (4 files)
  [FAIL]  Skill files (7 files)
  ...

  Result: 6 PASS · 2 WARN · 6 FAIL
  Recommendation snapshot saved.

Then fix everything:

npx bkit-doctor fix --yes

That's it. Missing directories created, config files scaffolded, agent definitions generated — all without touching anything that already exists.

Three things that matter

1. Diagnose: 14 checks, one command

bkit-doctor check inspects your project for 14 items across 6 categories: directory structure, config files, documentation scaffolds, agent definitions, skill files, templates, and policies.

Hard failures (missing .claude/ or CLAUDE.md) return exit code 1. Everything else is a warning. Simple.

2. Fix: scaffold what's missing

bkit-doctor fix --yes runs diagnosis, figures out what's missing, and creates it. One command, no prompts.

Want to see what it would do first?

bkit-doctor fix --dry-run

You can also pick specific targets:

bkit-doctor init --target hooks-json
bkit-doctor init --targets agents-core,docs-core

Or use presets for different project sizes:

bkit-doctor preset list
# default  — full structure (8 targets)
# lean     — minimal (config + agents only)
# workflow-core — agents + skills + templates + policies
# docs     — documentation scaffold only

3. Safe by design

This was non-negotiable: existing files are never overwritten unless you explicitly pass --overwrite. Even then, --backup creates copies before touching anything.

No surprises. No lost work. Preview everything with --dry-run.

When you'd actually use this

Starting a new project:

mkdir my-app && cd my-app
git init
npx bkit-doctor fix --yes
# Full AI-friendly project structure in seconds

Adding structure to an existing project:

cd existing-project
npx bkit-doctor check          # see what's missing
npx bkit-doctor fix --dry-run  # preview the fix
npx bkit-doctor fix --yes      # apply it

CI gate for project health:

# .github/workflows/check.yml
- name: Verify project structure
  run: npx bkit-doctor check
  # exits 1 if .claude/ or CLAUDE.md is missing

About bkit

bkit-doctor was inspired by bkit, a PDCA-based development workflow framework for Claude Code. I learned a lot about structured AI collaboration from bkit's methodology, and that shaped how this tool thinks about project structure.

That said — bkit-doctor is fully independent. It doesn't require bkit, doesn't include bkit code, and works with any AI coding tool. If you do use bkit, the scaffolding is optimized for its workflow. If you don't, you still get a clean, well-organized project structure.

Try it

npx bkit-doctor check

GitHub: github.com/dotoricode/bkit-doctor
npm: npmjs.com/package/bkit-doctor

If this solves a problem you've had, a star on the repo would be appreciated. And if you have ideas for additional checks or presets, issues and PRs are welcome.

bkit-doctor is an independent open-source project (Apache 2.0). It is not affiliated with the bkit team.