v2.0.2: fix contract bugs, trim bloat, soften overclaims

Contract fixes:
- Implementer no longer claims "only agent that modifies code"
- Debugger autonomous mode scoped: approval gates still apply
- Lessons format adds Agent field for filtering
- Rename AGENTS_CONTRACT → BLACKBOX_CONTRACT

Claims fixes (via fabric analyze_claims):
- "Constant velocity" → "Sustained velocity"
- Broaden attribution: Steenberg + Parnas (1972)
- Strip "autonomous" from top-level descriptions

Repo cleanup:
- Delete enhanced/ (orphaned pre-agent prompts)
- Delete docs/legacy/ (deprecated commands/skills)
- Consolidate 4 redundant doc files into AGENTS.md
- Restore README.md, add CLAUDE.md
- Bump agent.json to v2.0.2

Author: gl0bal01

CHANGELOG.md

@@ -1,5 +1,23 @@
 # CHANGELOG — Black Box Architecture Agents
 
+## v2.0.2 — 2026-03-20
+
+### Contract fixes and repo cleanup
+
+| What | Why |
+|---|---|
+| Fixed implementer claiming "only agent that modifies code" | Debugger also has write access — claim was false |
+| Clarified debugger autonomous mode scope | Approval gates (Rule 5) still apply during autonomous fixes — tension was unresolved |
+| Added `Agent` field to lessons.md format (Rule 10) | Needed for filtering lessons by agent at session start |
+| Bumped agent.json version to 2.0.2 | Was stuck at 2.0.0 despite v2.0.1 changes |
+| Deleted `enhanced/` directory | Orphaned pre-agent prompts, no agent referenced them |
+| Deleted `docs/legacy/` directory | Commands/skills marked "not recommended" — removed rather than maintaining dead code |
+| Consolidated docs: removed WORKFLOWS.md, USAGE.md, INSTALLATION.md, INTEGRATION_EXAMPLES.md | Same 5 workflows described in 4+ files. AGENTS.md is the single source now |
+| Restored README.md | Entry point for GitHub visitors was missing |
+| Stripped legacy references from AGENTS.md, CONTRIBUTING.md | Removed references to deleted files/directories |
+
+---
+
 ## v2.0.1 — 2026-02-25
 
 ### Post-review fixes
@@ -36,7 +54,7 @@
 
 ---
 
-### 📝 AGENTS_CONTRACT.md
+### 📝 BLACKBOX_CONTRACT.md
 
 | What changed | Why |
 |---|---|

CLAUDE.md

@@ -0,0 +1,48 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Project Is
+
+Black Box Architecture Agents — a system of five coordinated AI agents that help developers maintain and improve software architecture following black-box design principles (Eskil Steenberg's philosophy). This is a **documentation-only project** (no executables, no build system).
+
+## Architecture
+
+```
+User Request → arch-orchestrator (Opus, entry point)
+                ├→ arch-analyzer   (Sonnet, read-only, maps boundaries/violations)
+                ├→ arch-planner    (Opus, read-only, designs modules/roadmaps)
+                ├→ arch-implementer (Sonnet, write access, executes plans)
+                └→ arch-debugger   (Sonnet, write access, isolates/fixes bugs)
+```
+
+All agents are governed by `agents/BLACKBOX_CONTRACT.md` (13 global rules). The orchestrator classifies requests and delegates via HANDOFF packets.
+
+**Workflows**: Analysis only | Planning only | Full refactoring (analyze → plan → approve → implement) | Debug & fix | Complete transformation (all agents)
+
+## Key Directories
+
+- `agents/` — Agent specs + `agent.json` registry + `BLACKBOX_CONTRACT.md` shared rules
+- `docs/` — AGENTS (system guide), PRINCIPLES (philosophy), EXAMPLES (code), CONTRIBUTING
+- `examples/` — Multi-language before/after examples (Python, TypeScript, Go, Rust, PHP, C)
+- `tasks/` — Persistent session state: `lessons.md` (self-improvement) + `todo.md` (tracking)
+
+## Critical Conventions
+
+- **Scope discipline**: Touch only what's required. List nearby issues as POTENTIAL FOLLOW-UPS.
+- **Approval gates (⛔)**: Hard stops before adding deps, changing APIs/schemas, deleting code, widening permissions.
+- **Evidence minimums**: ≥3 file:line references per architectural claim.
+- **Commit discipline**: `git add -u` (never `-A`), checkpoint before non-trivial work, atomic commits per changeset.
+- **Self-improvement loop**: After corrections, update `tasks/lessons.md` with mistake → rule → agent → date.
+- **Session start**: Agents read `tasks/lessons.md` first to apply past learnings.
+
+## Installation (into target projects)
+
+```bash
+mkdir -p .claude/agents
+cp -r agents/* .claude/agents/
+```
+
+## No Build/Test/Lint
+
+Pure documentation project. No commands to run. Validate by reading agent specs and ensuring contract compliance.

README.md

@@ -1,125 +1,61 @@
-# Black Box Architecture
+# Black Box Architecture Agents
 
-> Transform any codebase into modular, maintainable "black boxes".
+AI agents for maintaining and improving software architecture using black-box design principles — inspired by [Eskil Steenberg's lecture](https://www.youtube.com/watch?v=sSpULGNHyoI) and rooted in information hiding (Parnas, 1972).
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](docs/CONTRIBUTING.md)
+Five coordinated specialists — analyze, plan, implement, debug — governed by a shared contract that enforces scope discipline, evidence minimums, approval gates, and a self-improvement loop.
 
-AI agents for **Claude Code** that enforce replaceable, modular architecture with built-in approval gates, commit discipline, and a self-improvement loop.
-
-## What This Is
-
-Five coordinated agents that apply [Eskil Steenberg's](https://www.youtube.com/watch?v=sSpULGNHyoI) battle-tested principles:
-
-- **Black box interfaces** - Clean APIs between modules
-- **Replaceable components** - If you can't understand it, rewrite it
-- **Constant velocity** - Write 5 lines today vs. edit 1 line later
-- **Single responsibility** - One module, one person
-
-## Quick Start
+## Quick Install
 
 ```bash
-# Clone the repository
 git clone https://github.com/gl0bal01/black-box-architecture.git
 
-# Install agents + task files for your project
+# Project-specific
 mkdir -p .claude/agents
 cp -r black-box-architecture/agents/* .claude/agents/
-mkdir -p tasks
-cp -r black-box-architecture/tasks/* tasks/
+
+# Or personal (all projects)
+cp -r black-box-architecture/agents/* ~/.claude/agents/
 ```
 
 ## Agents
 
-The agent system follows black box principles itself — specialized agents with clear responsibilities:
-
-| Agent | Role | Model | What it does |
+| Agent | Role | Model | Writes Code |
 |-------|------|-------|-------------|
-| **arch-orchestrator** | Entry point | Opus | Classifies requests, delegates, enforces approval gates, emits PASS/CONCERNS/FAIL/BLOCKED verdict |
-| **arch-analyzer** | Analysis | Sonnet | Maps module boundaries, coupling, violations. Read-only. Min 3 `file:line` per claim |
-| **arch-planner** | Design | Opus | Designs boundaries, interfaces, phased roadmaps. Simplicity check on non-trivial designs |
-| **arch-implementer** | Implementation | Sonnet | Executes approved plans. Atomic commits per changeset. Only agent that modifies code |
-| **arch-debugger** | Debugging | Sonnet | Isolates bugs to contract boundaries. Autonomous mode — just fix it. Captures lessons |
-
-### Workflows
-
-| Request | Flow |
-|---------|------|
-| Analysis only | Analyzer → synthesize |
-| Plan only | Planner → request approval |
-| Implement approved plan | Implementer |
-| Debug | Debugger → optionally Analyzer if architecture unclear |
-| Refactor toward black-box | Analyzer → Planner → **APPROVAL** → Implementer |
-| New feature | Planner → **APPROVAL** → Implementer |
-
-## What's New in v2.0
-
-- **Self-improvement loop** — agents review `tasks/lessons.md` at session start, update it after corrections. Mistakes don't repeat across sessions
-- **Task tracking** — persistent progress in `tasks/todo.md`. Resume work after interruptions
-- **Commit discipline** — `git add -u` before and after each changeset. Atomic, bisectable history. Never `git add -A`
-- **Goal-backward verification** — SUCCESS CRITERIA MET WHEN defines what done looks like, separate from HOW TO VERIFY
-- **Quality gate verdicts** — PASS / CONCERNS / FAIL / BLOCKED instead of silent self-assessed checklists
-- **Approval gates** — hard stops for deps, public API, schema, deletions, permission widening
-- **Session start checklists** — every agent loads lessons and context before working
-- **Debugger autonomous mode** — given a bug report, just fix it. Escalate only when genuinely blocked
-
-See [CHANGELOG.md](CHANGELOG.md) for full details.
-
-## Best Daily Workflow
-
-1. Use `arch-orchestrator` for most tasks — it picks the right workflow
-2. Concise output by default (5-12 lines). Full reports only when needed
-3. Approve any dependency, public API, or schema changes explicitly
-4. Check `tasks/lessons.md` periodically — it captures what the agents learned
-
-## How It Works
-
-- A [shared contract](agents/AGENTS_CONTRACT.md) governs all agent behavior (13 rules)
-- Agents default to concise outputs and switch to full reports when warranted
-- Approval gates prevent risky changes without explicit sign-off
-- Every architectural claim requires min 3 `file:line` evidence points
-- Agents commit before and after each changeset for safe rollback
-- Corrections are captured in `tasks/lessons.md` and reviewed next session
-
-## Core Philosophy
-
-**"It's faster to write 5 lines of code today than to write 1 line today and then have to edit it in the future."**
-— Eskil Steenberg
-
-1. **Primitive-First Design** - Identify core data types that flow through your system
-2. **Black Box Boundaries** - Modules communicate only through documented interfaces
-3. **Replaceable Components** - Any module can be rewritten using only its interface
-4. **Single Responsibility** - One module = one person can own it
-5. **Wrap Dependencies** - Never depend directly on code you don't control
-
-## Documentation
-
-- **[Agent System Guide](docs/AGENTS.md)** - Complete agent documentation
-- **[Workflows Guide](docs/WORKFLOWS.md)** - Step-by-step examples for each agent
-- **[Integration Examples](docs/INTEGRATION_EXAMPLES.md)** - How agents coordinate
-- **[Principles Guide](docs/PRINCIPLES.md)** - Eskil Steenberg's methodology explained
-- **[Code Examples](docs/EXAMPLES.md)** - Before/after transformations in multiple languages
-- **[Agent Specifications](agents/agent.json)** - Technical specs and policies
-- **[Contributing Guide](docs/CONTRIBUTING.md)** - How to contribute
+| **arch-orchestrator** | Entry point. Classifies, delegates, synthesizes. | Opus | No |
+| **arch-analyzer** | Maps module boundaries, coupling, violations. | Sonnet | No |
+| **arch-planner** | Designs modules, interfaces, migration roadmaps. | Opus | No |
+| **arch-implementer** | Executes approved plans with commit discipline. | Sonnet | Yes (requires approval) |
+| **arch-debugger** | Isolates bugs to contract boundaries, fixes autonomously. | Sonnet | Yes (approval gates apply) |
 
-## Real-World Examples
+All agents follow `agents/BLACKBOX_CONTRACT.md` — 13 rules covering scope discipline, evidence requirements, approval gates, commit checkpoints, and self-improvement.
 
-See [`examples/`](examples/) for complete before/after refactoring examples in Python, TypeScript, Go, Rust, C, and PHP.
+## Usage
 
-## Legacy Prompts
-
-Skills and commands in `docs/legacy/` are kept for compatibility but are no longer the recommended path. Use agents instead.
+```
+"Ask arch-orchestrator to analyze UserService and propose black-box boundaries"
+"Ask arch-analyzer to find coupling issues in src/services/"
+"Ask arch-planner to design a payment processing module"
+"Ask arch-implementer to execute the approved refactoring plan"
+"Ask arch-debugger to isolate and fix the checkout bug"
+```
 
-## Related Resources
+## Workflows
 
-- [Eskil Steenberg: Architecting LARGE Software Projects](https://www.youtube.com/watch?v=sSpULGNHyoI) - The foundation of everything here
+| Workflow | Agents | Approval Gate |
+|----------|--------|---------------|
+| Analysis only | Analyzer | — |
+| Planning only | Planner | — |
+| Full refactoring | Analyzer → Planner → Implementer | After plan, before implementation |
+| Debug & fix | Debugger → (Implementer) | Before non-trivial fixes |
+| Complete transformation | All agents in sequence | After plan + between phases |
 
-## Contributing
+## Documentation
 
-Contributions welcome! See [CONTRIBUTING.md](docs/CONTRIBUTING.md).
+- [Agent System Guide](docs/AGENTS.md) — Architecture, agents, workflows, troubleshooting
+- [Black Box Principles](docs/PRINCIPLES.md) — Design philosophy (Steenberg, Parnas)
+- [Code Examples](docs/EXAMPLES.md) — Before/after refactorings in 6 languages
+- [Contributing](docs/CONTRIBUTING.md) — How to contribute
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) for details.
-
----
+MIT

agents/AGENTS_CONTRACT.md agents/BLACKBOX_CONTRACT.mdagents/AGENTS_CONTRACT.md renamed to agents/BLACKBOX_CONTRACT.md

@@ -7,7 +7,7 @@ Shared rules for all agents. Individual agent files contain only role-specific b
 
 ## Operating Goals
 
-- **Constant velocity**: make changes that stay easy to edit tomorrow
+- **Sustained velocity**: make changes that stay easy to edit tomorrow
 - **Smallest correct change**: surgical diffs over "cleanup"
 - **Reviewability**: optimize for a human reviewing side-by-side in an IDE
 - **Staff engineer bar**: before submitting, ask "would a staff engineer approve this?"
@@ -116,6 +116,7 @@ Format:
 ## Lesson: [short title]
 **Mistake**: what went wrong
 **Rule**: what to do instead
+**Agent**: which agent this applies to (or "all")
 **Date**: YYYY-MM-DD
 ```
 

agents/agent.json

@@ -1,7 +1,7 @@
 {
   "name": "black-box-architecture-agents",
-  "version": "2.0.0",
-  "description": "Specialized agents for autonomous architectural work. Coordinated system for analysis, planning, implementation, and debugging with self-improvement loop and approval gates.",
+  "version": "2.0.2",
+  "description": "Specialized agents for architectural work with human-in-the-loop approval gates. Coordinated system for analysis, planning, implementation, and debugging with self-improvement loop.",
   "author": "gl0bal01",
   "license": "MIT",
   "keywords": [
@@ -68,7 +68,7 @@
     },
     "implementer": {
       "name": "Architecture Implementer",
-      "description": "Executes approved plans with commit checkpoints and scope discipline.",
+      "description": "Primary agent for planned code changes. Executes approved plans with commit checkpoints and scope discipline.",
       "file": "arch-implementer.md",
       "role": "implementation",
       "model": "sonnet",
@@ -90,7 +90,7 @@
         "can_modify_code": true,
         "can_delegate": false,
         "may_request_agent": "implementer",
-        "autonomous_mode": true,
+        "autonomous_mode": "internal module logic only; approval gates still apply",
         "writes_to": "tasks/lessons.md"
       }
     }
@@ -123,7 +123,7 @@
     }
   },
   "files": {
-    "contract": "AGENTS_CONTRACT.md",
+    "contract": "BLACKBOX_CONTRACT.md",
     "lessons": "tasks/lessons.md",
     "todo": "tasks/todo.md"
   },

agents/arch-analyzer.md

@@ -9,7 +9,7 @@ model: sonnet
 
 **Role**: Explore a codebase to map module boundaries, coupling, and black-box violations.
 
-Follows `AGENTS_CONTRACT.md`. Read-only — never modifies code.
+Follows `BLACKBOX_CONTRACT.md`. Read-only — never modifies code.
 
 ---
 
@@ -70,4 +70,4 @@ Follows `AGENTS_CONTRACT.md`. Read-only — never modifies code.
 **NEXT**
 - proceed to Planner? remaining questions?
 
-(Full report only if requested: Appendix A in `AGENTS_CONTRACT.md`)
+(Full report only if requested: Appendix A in `BLACKBOX_CONTRACT.md`)

agents/arch-debugger.md

@@ -9,7 +9,7 @@ model: sonnet
 
 **Role**: Isolate bugs to module/contract boundaries, produce minimal repro, fix without breaking boundaries.
 
-Follows `AGENTS_CONTRACT.md`.
+Follows `BLACKBOX_CONTRACT.md`.
 
 ---
 
@@ -69,6 +69,10 @@ When given a bug report: just fix it.
 - Fix failing CI tests without being told how
 - Only escalate when genuinely blocked (ambiguous contract, approval gate hit)
 
+**Scope of autonomy**: Debugger may freely fix internal module logic.
+Contract approval gates (Rule 5) still apply — stop and ask before:
+adding deps, changing public APIs, changing schemas, deleting code beyond the fix, or widening permissions.
+
 ---
 
 ## Output (concise default)
@@ -94,4 +98,4 @@ When given a bug report: just fix it.
 **LESSON CAPTURED**
 - entry added to `tasks/lessons.md`
 
-(Full report only if requested: Appendix D in `AGENTS_CONTRACT.md`)
+(Full report only if requested: Appendix D in `BLACKBOX_CONTRACT.md`)

agents/arch-implementer.md

@@ -9,7 +9,8 @@ model: sonnet
 
 **Role**: Execute approved plans via small, verifiable changes that preserve black-box boundaries.
 
-Follows `AGENTS_CONTRACT.md`. Only agent that modifies code — requires prior approval.
+Follows `BLACKBOX_CONTRACT.md`. Primary agent for planned code changes — requires prior approval.
+(Debugger also has write access for autonomous bug fixes.)
 
 ---
 
@@ -92,4 +93,4 @@ Never proceed without explicit approval for:
 **BLOCKED** (only if needed)
 - exact questions + info required
 
-(Full report only if requested: Appendix C in `AGENTS_CONTRACT.md`)
+(Full report only if requested: Appendix C in `BLACKBOX_CONTRACT.md`)

agents/arch-orchestrator.md

@@ -9,7 +9,7 @@ model: opus
 
 **Role**: Coordinate architectural work. Entry point for all black-box architecture requests.
 
-Follows `AGENTS_CONTRACT.md` (shared rules). Contract wins on conflicts.
+Follows `BLACKBOX_CONTRACT.md` (shared rules). Contract wins on conflicts.
 
 ---
 

agents/arch-planner.md

@@ -9,7 +9,7 @@ model: opus
 
 **Role**: Design black-box module boundaries and implementation roadmap.
 
-Follows `AGENTS_CONTRACT.md`. Read-only — never modifies code.
+Follows `BLACKBOX_CONTRACT.md`. Read-only — never modifies code.
 
 ---
 
@@ -80,4 +80,4 @@ For each module:
 - **POTENTIAL CONCERNS**
 - **NEXT** (approval request + first implementation step)
 
-(Full plan only if requested: Appendix B in `AGENTS_CONTRACT.md`)
+(Full plan only if requested: Appendix B in `BLACKBOX_CONTRACT.md`)