TheTechOddBug · pull · Feb 5, 2026 · Feb 5, 2026 · Feb 5, 2026 · Feb 5, 2026
diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl
diff --git a/README.md b/README.md
diff --git a/docs/ai-development-best-practices.md b/docs/ai-development-best-practices.md
@@ -56,7 +56,7 @@ A canonical, enumerated list of best practices derived from comprehensive analys
 
 22. **Context Optimization**: Match AI tool selection to task complexity using [Context Optimization](../experiments/README.md#context-optimization) and defined criteria: simple models for queries <500 tokens, complex models for architecture decisions >2000 tokens.
 
-23. **Image Spec**: Use diagrams, mockups, and flows as primary specifications for complex needs using [Image Spec](../experiments/README.md#image-spec), supplemented with structured text for precise details.
+23. **Image Spec**: Use diagrams, mockups, and flows as primary specifications for complex needs using [Image Spec](../README.md#image-spec), supplemented with structured text for precise details.
 
 24. **Version Knowledge Assets**: Treat AI development knowledge as code with semantic versioning, peer review processes, and automated quality checks.
 
@@ -66,9 +66,9 @@ A canonical, enumerated list of best practices derived from comprehensive analys
 
 26. **Smart Defaults with Extensibility**: Design AI development tools that work perfectly with no configuration while supporting advanced customization options.
 
-27. **Self-Documenting Commands**: Include comprehensive built-in help with usage patterns, examples, and parameter explanations in every AI development tool using [Custom Commands](../experiments/README.md#custom-commands).
+27. **Self-Documenting Commands**: Include comprehensive built-in help with usage patterns, examples, and parameter explanations in every AI development tool using [Custom Commands](../README.md#custom-commands).
 
-28. **Hooks-Based Governance**: Implement flexible hook systems for automated monitoring, logging, and policy enforcement at critical development workflow points using [Event Automation](../experiments/README.md#event-automation).
+28. **Hooks-Based Governance**: Implement flexible hook systems for automated monitoring, logging, and policy enforcement at critical development workflow points using [Event Automation](../README.md#event-automation).
 
 29. **Modular Command Architecture**: Organize AI tools into clear categories with well-defined scopes (project-specific vs. machine-wide) for flexible workflows.
 

diff --git a/...ents/examples/centralized-rules/README.md → examples/centralized-rules/README.md b/...ents/examples/centralized-rules/README.md → examples/centralized-rules/README.md
diff --git a/...-rules/gateway-strategy/README-GATEWAY.md → ...-rules/gateway-strategy/README-GATEWAY.md b/...-rules/gateway-strategy/README-GATEWAY.md → ...-rules/gateway-strategy/README-GATEWAY.md
diff --git a/.../gateway-strategy/ai-dev-cli/package.json → .../gateway-strategy/ai-dev-cli/package.json b/.../gateway-strategy/ai-dev-cli/package.json → .../gateway-strategy/ai-dev-cli/package.json
diff --git a/...es/gateway-strategy/ai-dev-cli/src/cli.ts → ...es/gateway-strategy/ai-dev-cli/src/cli.ts b/...es/gateway-strategy/ai-dev-cli/src/cli.ts → ...es/gateway-strategy/ai-dev-cli/src/cli.ts
diff --git a/.../gateway-strategy/ai-gateway/package.json → .../gateway-strategy/ai-gateway/package.json b/.../gateway-strategy/ai-gateway/package.json → .../gateway-strategy/ai-gateway/package.json
diff --git a/...y-strategy/ai-gateway/src/claudeClient.ts → ...y-strategy/ai-gateway/src/claudeClient.ts b/...y-strategy/ai-gateway/src/claudeClient.ts → ...y-strategy/ai-gateway/src/claudeClient.ts
diff --git a/...gateway-strategy/ai-gateway/src/server.ts → ...gateway-strategy/ai-gateway/src/server.ts b/...gateway-strategy/ai-gateway/src/server.ts → ...gateway-strategy/ai-gateway/src/server.ts
diff --git a/...teway-strategy/org-ai-client/package.json → ...teway-strategy/org-ai-client/package.json b/...teway-strategy/org-ai-client/package.json → ...teway-strategy/org-ai-client/package.json
diff --git a/...teway-strategy/org-ai-client/src/index.ts → ...teway-strategy/org-ai-client/src/index.ts b/...teway-strategy/org-ai-client/src/index.ts → ...teway-strategy/org-ai-client/src/index.ts
diff --git a/...ules/sync-strategy/create-central-repo.sh → ...ules/sync-strategy/create-central-repo.sh b/...ules/sync-strategy/create-central-repo.sh → ...ules/sync-strategy/create-central-repo.sh
diff --git a/...mple-central-repo/base/universal-rules.md → ...mple-central-repo/base/universal-rules.md b/...mple-central-repo/base/universal-rules.md → ...mple-central-repo/base/universal-rules.md
diff --git a/.../example-central-repo/frameworks/react.md → .../example-central-repo/frameworks/react.md b/.../example-central-repo/frameworks/react.md → .../example-central-repo/frameworks/react.md
diff --git a/.../example-central-repo/languages/python.md → .../example-central-repo/languages/python.md b/.../example-central-repo/languages/python.md → .../example-central-repo/languages/python.md
diff --git a/...ized-rules/sync-strategy/sync-ai-rules.sh → ...ized-rules/sync-strategy/sync-ai-rules.sh b/...ized-rules/sync-strategy/sync-ai-rules.sh → ...ized-rules/sync-strategy/sync-ai-rules.sh
diff --git a/...iments/examples/custom-commands/README.md → examples/custom-commands/README.md b/...iments/examples/custom-commands/README.md → examples/custom-commands/README.md
diff --git a/...ples/custom-commands/claude-settings.json → ...ples/custom-commands/claude-settings.json b/...ples/custom-commands/claude-settings.json → ...ples/custom-commands/claude-settings.json
diff --git a/...ustom-commands/commands/implement-spec.md → ...ustom-commands/commands/implement-spec.md b/...ustom-commands/commands/implement-spec.md → ...ustom-commands/commands/implement-spec.md
diff --git a/...ples/custom-commands/commands/refactor.md → ...ples/custom-commands/commands/refactor.md b/...ples/custom-commands/commands/refactor.md → ...ples/custom-commands/commands/refactor.md
diff --git a/...custom-commands/commands/safe-refactor.md → ...custom-commands/commands/safe-refactor.md b/...custom-commands/commands/safe-refactor.md → ...custom-commands/commands/safe-refactor.md
diff --git a/...stom-commands/commands/security-review.md → ...stom-commands/commands/security-review.md b/...stom-commands/commands/security-review.md → ...stom-commands/commands/security-review.md
diff --git a/...examples/custom-commands/commands/test.md → examples/custom-commands/commands/test.md b/...examples/custom-commands/commands/test.md → examples/custom-commands/commands/test.md
diff --git a/...custom-commands/implement-spec-example.md → ...custom-commands/implement-spec-example.md b/...custom-commands/implement-spec-example.md → ...custom-commands/implement-spec-example.md
@@ -79,5 +79,5 @@ EOF
 
 ## Related Patterns
 
-- [Spec-Driven Development](../../../README.md#spec-driven-development)
-- [Automated Traceability](../../../README.md#automated-traceability)
+- [Spec-Driven Development](../../README.md#spec-driven-development)
+- [Automated Traceability](../../README.md#automated-traceability)
diff --git a/.../custom-commands/safe-refactor-example.md → .../custom-commands/safe-refactor-example.md b/.../custom-commands/safe-refactor-example.md → .../custom-commands/safe-refactor-example.md
@@ -92,5 +92,5 @@ Automatic approval if ALL conditions met:
 
 ## Related Patterns
 
-- [Guided Refactoring](../../../README.md#guided-refactoring)
-- [Testing Orchestration](../../README.md#testing-orchestration)
+- [Guided Refactoring](../../README.md#guided-refactoring)
+- [Testing Orchestration](../../experiments/README.md#testing-orchestration)
diff --git a/...ustom-commands/security-review-example.md → ...ustom-commands/security-review-example.md b/...ustom-commands/security-review-example.md → ...ustom-commands/security-review-example.md
@@ -95,5 +95,5 @@ if (!API_KEY) throw new Error("STRIPE_API_KEY required")
 
 ## Related Patterns
 
-- [Security Orchestration](../../../README.md#security-orchestration)
-- [Security Sandbox](../../../README.md#security-sandbox)
+- [Security Orchestration](../../README.md#security-orchestration)
+- [Security Sandbox](../../README.md#security-sandbox)
diff --git a/.../examples/custom-commands/test-example.md → examples/custom-commands/test-example.md b/.../examples/custom-commands/test-example.md → examples/custom-commands/test-example.md
@@ -104,5 +104,5 @@ git diff --name-only HEAD~1 HEAD
 
 ## Related Patterns
 
-- [Testing Orchestration](../../README.md#testing-orchestration)
-- [Suite Health](../../README.md#suite-health)
+- [Testing Orchestration](../../experiments/README.md#testing-orchestration)
+- [Suite Health](../../experiments/README.md#suite-health)
diff --git a/...ments/examples/event-automation/README.md → examples/event-automation/README.md b/...ments/examples/event-automation/README.md → examples/event-automation/README.md
diff --git a/...les/event-automation/claude-settings.json → ...les/event-automation/claude-settings.json b/...les/event-automation/claude-settings.json → ...les/event-automation/claude-settings.json
diff --git a/...xamples/event-automation/security-hook.sh → examples/event-automation/security-hook.sh b/...xamples/event-automation/security-hook.sh → examples/event-automation/security-hook.sh
diff --git a/examples/image-spec/README.md b/examples/image-spec/README.md
@@ -0,0 +1,28 @@
+# Image Spec Example
+
+This example provides a repeatable, image-first workflow for the [Image Spec](../../README.md#image-spec) pattern: use diagrams and mockups as primary specifications, then iterate with annotated visuals.
+
+## Workflow
+
+1. Create a **single** high-level diagram (architecture, UI mock, or flow) with labels and constraints (ports, component names, state transitions).
+2. Attach the image and provide a short prompt that clarifies only what the image cannot (tech stack, scope, constraints).
+3. Run the generated result, capture a screenshot, and annotate what’s missing or incorrect.
+4. Re-attach the annotated image and iterate on one slice at a time.
+
+## Recommended Image Set
+
+- `architecture.png`: components + boundaries + ports
+- `data-model.png`: fields + relationships + example payloads
+- `ui-mock.png`: layout + key interactions
+- `flow.png`: sequence of steps + decision points
+
+## Prompt Template
+
+```text
+Build the system from the attached images.
+Tech stack: <stack>
+Scope: <what to implement first>
+Constraints: <performance/security/testing constraints>
+Output: code + tests + a short runbook
+```
+
diff --git a/examples/progressive-disclosure/README.md b/examples/progressive-disclosure/README.md
@@ -0,0 +1,27 @@
+# Progressive Disclosure Example
+
+This example provides a tool-agnostic starter layout for implementing the [Progressive Disclosure](../../README.md#progressive-disclosure) pattern in a real repository.
+
+## Goal
+
+Keep a small, universal rules file that applies to every task, and load specialized rules only when the work context requires them (security, API design, testing, CI/CD, etc.).
+
+## Starter Layout
+
+```text
+.ai/
+├── CLAUDE.md                  # Universal rules + routing hints (<60 lines)
+├── rules/
+│   ├── security/              # secrets, auth, dependencies
+│   ├── development/           # api-design, database, testing
+│   ├── operations/            # deployment, monitoring, cicd
+│   └── architecture/          # patterns, performance
+└── prompts/                   # reusable task templates
+```
+
+## Suggested Workflow
+
+1. Keep `.ai/CLAUDE.md` minimal and explicit about **when** to load specialized rules.
+2. Add small, focused rule files under `.ai/rules/` (aim for <100 lines each).
+3. Optionally combine with [Event Automation](../../README.md#event-automation) to auto-load the relevant rules before edits, writes, or test runs.
+