Skip to content

Commit 0b8e382

Browse files
jacoponeclaude
jacopone
and
claude
committed
docs: fix stale references after claude-automation extraction
Phase 1 documentation cleanup after scripts/claude-automation was extracted to separate repository (github:jacopone/claude-nixos-automation) on 2025-10-03. Updates: - CLAUDE_ORCHESTRATION.md: Updated all references to external repository - Added extraction note at top with repository links - Updated Level 1 & 2 generator sources - Updated manual trigger commands to use nix run - Updated troubleshooting and maintenance sections - Bumped architecture version to 2.1 - README.md: Updated automation reference to external flake - Changed scripts/claude-automation/README.md link to GitHub URL - docs/automation/claude-automation-system.md: Deprecated with redirect - Created deprecation notice pointing to CLAUDE_ORCHESTRATION.md - Moved original implementation docs to docs/archive/ - Rationale: Implementation details belong in source repo - Cleanup: Deleted empty templates/ai-quality-devenv/ directory - Only contained .claude/settings.local.json - Superseded by ai-project-orchestration repository - Added comprehensive documentation audit report - docs/DOCUMENTATION_AUDIT_2025-10-06.md - Identified 3 stale files, 1 empty directory - 93% documentation accuracy (40/43 files current) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent b93c6a5 commit 0b8e382

File tree

6 files changed

+851
-294
lines changed

6 files changed

+851
-294
lines changed

‎CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,13 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
2525
### Changed
2626
- Fish abbreviations increased to 58
2727

28+
### Documentation
29+
- Updated CLAUDE_ORCHESTRATION.md to reflect claude-automation extraction (2025-10-03)
30+
- Updated README.md automation reference to external repository
31+
- Deprecated docs/automation/claude-automation-system.md with redirect to external repo
32+
- Created docs/archive/ directory for historical documentation
33+
- Deleted empty templates/ai-quality-devenv/ directory (superseded by ai-project-orchestration)
34+
2835
---
2936

3037
## [2025-10-05]

‎CLAUDE_ORCHESTRATION.md‎

Lines changed: 76 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@
22

33
**Three-Level Auto-Generation System for Enterprise NixOS Development**
44

5+
> **📦 Note**: The claude-automation system was extracted to a separate repository on 2025-10-03.
6+
> - **Repository**: https://github.com/jacopone/claude-nixos-automation
7+
> - **Local Clone**: `~/claude-nixos-automation`
8+
> - **Integration**: Via Nix flake input in `flake.nix`
9+
510
## Overview
611

712
This NixOS configuration includes a **three-level Claude Code orchestration system** that automatically generates and maintains Claude configuration files across different scopes.
@@ -22,7 +27,7 @@ On rebuild On rebuild High-quality source
2227
### Level 1: System-Wide Configuration
2328

2429
**File**: `~/.claude/CLAUDE.md`
25-
**Generated by**: `scripts/claude-automation/` package
30+
**Generated by**: `claude-nixos-automation` (external Nix flake)
2631
**Triggered by**: Every `nixos-rebuild` via `./rebuild-nixos`
2732
**Scope**: ALL Claude Code projects on this system
2833

@@ -56,7 +61,7 @@ On rebuild On rebuild High-quality source
5661
### Level 2: Project-Level Configuration
5762

5863
**File**: `./CLAUDE.md` (in nixos-config root)
59-
**Generated by**: `scripts/claude-automation/` package
64+
**Generated by**: `claude-nixos-automation` (external Nix flake)
6065
**Triggered by**: Every `nixos-rebuild` via `./rebuild-nixos`
6166
**Scope**: Working on the nixos-config repository
6267

@@ -90,10 +95,10 @@ On rebuild On rebuild High-quality source
9095

9196
### Level 3: Template-Level Configuration
9297

93-
**File**: `templates/ai-quality-devenv/.ai-templates/claude/CLAUDE.md`
98+
**File**: Templates in `ai-project-orchestration` repository
9499
**Maintained**: Manually (curated, high-quality)
95100
**Triggered**: Never auto-generated (preserved across rebuilds)
96-
**Scope**: New projects created from ai-quality-devenv template
101+
**Scope**: New projects created via `ai-init-greenfield` or `ai-init-brownfield`
97102

98103
**Content**:
99104
- Quality gate thresholds (CCN < 10, duplication < 5%, zero secrets)
@@ -178,19 +183,19 @@ claude-automation/
178183
The `./rebuild-nixos` script orchestrates the auto-generation:
179184

180185
```bash
181-
# In ./rebuild-nixos (after nixos-rebuild test)
186+
# In ./rebuild-nixos (after nixos-rebuild switch)
182187

183188
echo "📋 Updating Claude Code configurations..."
184189

185-
# Level 1: System-wide
186-
cd scripts && devenv shell python update-system-claude-v2.py
187-
# Generates ~/.claude/CLAUDE.md with tool inventory
188-
189-
# Level 2: Project-specific
190-
cd scripts && devenv shell python update-project-claude-v2.py
191-
# Generates ./CLAUDE.md with project workflows
192-
193-
echo "✅ Claude Code configurations updated"
190+
# Run automation from the claude-nixos-automation flake
191+
if (cd ~/nixos-config && nix run github:jacopone/claude-nixos-automation#update-all); then
192+
echo " ✅ Claude Code configurations updated"
193+
echo " - User policies: ~/.claude/CLAUDE-USER-POLICIES.md (preserved)"
194+
echo " - System CLAUDE.md: ~/.claude/CLAUDE.md (updated)"
195+
echo " - Project CLAUDE.md: ./CLAUDE.md (updated)"
196+
else
197+
echo " ⚠️ Failed to update Claude configs (continuing anyway)"
198+
fi
194199
```
195200

196201
**Workflow**:
@@ -262,22 +267,24 @@ cat ~/.claude/CLAUDE.md | grep "ripgrep-all"
262267
### Example 2: Creating New Project from Template
263268

264269
```bash
265-
# 1. Copy template
266-
cp -r templates/ai-quality-devenv ~/my-new-project
270+
# 1. Create project directory
271+
mkdir ~/my-new-project
267272
cd ~/my-new-project
268273

269-
# 2. Run interactive setup
270-
devenv shell
271-
init-ai-tools
272-
# Select "Claude Code"
274+
# 2. Initialize with ai-project-orchestration
275+
ai-init-greenfield
276+
# Or: ai-init-brownfield for legacy projects
273277

274-
# 3. Files created
278+
# 3. Activate environment
279+
direnv allow
280+
281+
# 4. Files created
275282
ls -la .claude/
276-
# CLAUDE.md (copied from Level 3 template)
283+
# CLAUDE.md (from ai-project-orchestration template)
277284
# settings.local.json
278285
# README.md
279286

280-
# 4. Claude reads:
287+
# 5. Claude reads:
281288
# - Level 1: ~/.claude/CLAUDE.md (system tools)
282289
# - Level 3: .claude/CLAUDE.md (quality standards)
283290
```
@@ -316,13 +323,14 @@ ls -la .claude/
316323

317324
**Manual trigger**:
318325
```bash
319-
cd ~/nixos-config/scripts
320-
devenv shell python update-system-claude-v2.py
326+
cd ~/nixos-config
327+
nix run github:jacopone/claude-nixos-automation#update-system
321328
```
322329

323330
**To modify template**:
324331
```bash
325-
nano scripts/claude-automation/templates/system-claude.j2
332+
cd ~/claude-nixos-automation
333+
nano claude_automation/templates/system-claude.j2
326334
```
327335

328336
---
@@ -333,26 +341,29 @@ nano scripts/claude-automation/templates/system-claude.j2
333341

334342
**Manual trigger**:
335343
```bash
336-
cd ~/nixos-config/scripts
337-
devenv shell python update-project-claude-v2.py
344+
cd ~/nixos-config
345+
nix run github:jacopone/claude-nixos-automation#update-project
338346
```
339347

340348
**To modify template**:
341349
```bash
342-
nano scripts/claude-automation/templates/project-claude.j2
350+
cd ~/claude-nixos-automation
351+
nano claude_automation/templates/project-claude.j2
343352
```
344353

345354
---
346355

347356
### Updating Level 3 (Template)
348357

349-
**Manual only**: Edit template source files
358+
**Manual only**: Edit template source files in ai-project-orchestration repository
350359

351360
```bash
352-
nano templates/ai-quality-devenv/.ai-templates/claude/CLAUDE.md
361+
cd ~/ai-project-orchestration
362+
nano templates/greenfield/.ai-templates/claude/CLAUDE.md
363+
# Or: templates/brownfield/.ai-templates/claude/CLAUDE.md
353364
```
354365

355-
**Changes apply**: When users run `init-ai-tools` in new projects
366+
**Changes apply**: When users run `ai-init-greenfield` or `ai-init-brownfield` in new projects
356367

357368
**Never auto-generated**: Preserves manual curation and quality
358369

@@ -362,23 +373,22 @@ nano templates/ai-quality-devenv/.ai-templates/claude/CLAUDE.md
362373

363374
### Issue: "Failed to update system-level Claude config"
364375

365-
**Check 1**: Package exists
376+
**Check 1**: External repository accessible
366377
```bash
367-
ls -la scripts/claude-automation/
368-
# Should show: generators/, parsers/, templates/, validators/
378+
ls -la ~/claude-nixos-automation/
379+
# Should show: claude_automation/, flake.nix, *.py scripts
369380
```
370381

371-
**Check 2**: DevEnv active
382+
**Check 2**: Flake input configured
372383
```bash
373-
cd scripts
374-
devenv shell
375-
python update-system-claude-v2.py
384+
nix flake metadata ~/nixos-config | grep claude-automation
385+
# Should show: claude-automation github:jacopone/claude-nixos-automation
376386
```
377387

378-
**Check 3**: .DO_NOT_DELETE marker present
388+
**Check 3**: Manual trigger
379389
```bash
380-
cat scripts/claude-automation/.DO_NOT_DELETE
381-
# Should show warning about critical infrastructure
390+
cd ~/nixos-config
391+
nix run github:jacopone/claude-nixos-automation#update-all
382392
```
383393

384394
---
@@ -388,8 +398,8 @@ cat scripts/claude-automation/.DO_NOT_DELETE
388398
**Solution**: Regenerate manually
389399
```bash
390400
mkdir -p ~/.claude
391-
cd ~/nixos-config/scripts
392-
devenv shell python update-system-claude-v2.py
401+
cd ~/nixos-config
402+
nix run github:jacopone/claude-nixos-automation#update-system
393403
```
394404

395405
---
@@ -400,7 +410,8 @@ devenv shell python update-system-claude-v2.py
400410
```bash
401411
./rebuild-nixos
402412
# OR
403-
cd scripts && devenv shell python update-project-claude-v2.py
413+
cd ~/nixos-config
414+
nix run github:jacopone/claude-nixos-automation#update-project
404415
```
405416

406417
---
@@ -409,10 +420,11 @@ cd scripts && devenv shell python update-project-claude-v2.py
409420

410421
**This should NEVER happen**: Level 3 is manually maintained.
411422

412-
If deleted:
423+
If deleted in ai-project-orchestration repository:
413424
```bash
414425
# Restore from git
415-
git restore templates/ai-quality-devenv/.ai-templates/claude/CLAUDE.md
426+
cd ~/ai-project-orchestration
427+
git restore templates/greenfield/.ai-templates/claude/CLAUDE.md
416428
```
417429

418430
---
@@ -446,33 +458,31 @@ git restore templates/ai-quality-devenv/.ai-templates/claude/CLAUDE.md
446458

447459
## Related Documentation
448460

449-
- **claude-automation package**: `scripts/claude-automation/README.md`
461+
- **claude-automation repository**: https://github.com/jacopone/claude-nixos-automation
462+
- **claude-automation README**: `~/claude-nixos-automation/README.md`
450463
- **System CLAUDE.md**: `~/.claude/CLAUDE.md` (auto-generated)
451464
- **Project CLAUDE.md**: `./CLAUDE.md` (auto-generated)
452-
- **Template CLAUDE.md**: `templates/ai-quality-devenv/.ai-templates/claude/CLAUDE.md`
465+
- **User policies**: `~/.claude/CLAUDE-USER-POLICIES.md` (user-maintained)
453466
- **Rebuild script**: `./rebuild-nixos`
454-
- **Update scripts**: `scripts/update-system-claude-v2.py`, `scripts/update-project-claude-v2.py`
455-
- **Template setup**: `templates/ai-quality-devenv/CLAUDE_CODE_SETUP.md`
467+
- **Template system**: `ai-init-greenfield` / `ai-init-brownfield` commands
456468

457469
---
458470

459471
## Critical Reminders
460472

461-
### DO NOT DELETE claude-automation Package
462-
463-
- ❌ It's NOT legacy code
464-
- ❌ It's NOT a duplicate folder
465-
- ✅ It IS critical infrastructure
466-
- ✅ It powers auto-generation on every rebuild
467-
- ✅ Deleting it breaks the system
473+
### External Repository Integration
468474

469-
See `scripts/claude-automation/README.md` and `.DO_NOT_DELETE` for details.
475+
- ✅ **claude-nixos-automation** is an external Nix flake
476+
- ✅ Integrated via `flake.nix` input
477+
- ✅ Powers auto-generation on every rebuild
478+
- ✅ Repository: https://github.com/jacopone/claude-nixos-automation
479+
- ✅ Local clone: `~/claude-nixos-automation`
470480

471-
### Naming Convention
481+
### Package Location
472482

473-
- **Directory**: `claude-automation/` (hyphenated)
474-
- **Import**: `claude_automation` (underscored)
475-
- **Standard Python practice** - they reference the SAME package
483+
- **External repo**: `~/claude-nixos-automation/` (outside nixos-config)
484+
- **Nix flake input**: Referenced in `flake.nix`
485+
- **No local scripts/**: Automation extracted to separate repository (2025-10-03)
476486

477487
### Manual vs Auto
478488

@@ -481,7 +491,8 @@ See `scripts/claude-automation/README.md` and `.DO_NOT_DELETE` for details.
481491

482492
---
483493

484-
**Architecture Version**: 2.0
485-
**Last Updated**: October 2025
494+
**Architecture Version**: 2.1
495+
**Last Updated**: 2025-10-06
486496
**Status**: Production
487497
**Orchestration**: Automatic via rebuild-nixos
498+
**Automation**: External flake (github:jacopone/claude-nixos-automation)

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -818,7 +818,7 @@ The system detects:
818818
### AI Development Integration
819819

820820
- **[docs/CURSOR_AI_QUALITY_INTEGRATION.md](docs/CURSOR_AI_QUALITY_INTEGRATION.md)** - Cursor AI and quality gates integration guide
821-
- **[scripts/claude-automation/README.md](scripts/claude-automation/README.md)** - Claude Code auto-generation system (CRITICAL INFRASTRUCTURE)
821+
- **[Claude NixOS Automation](https://github.com/jacopone/claude-nixos-automation)** - Claude Code auto-generation system (external flake)
822822

823823
### Tools & Configuration Guides
824824

0 commit comments

Comments
 (0)