Developer infrastructure scaffold + ATOM+SAGE intent-driven operations framework

kenl provides two complementary systems for professional software development:

1. Developer Infrastructure Scaffold: Production-ready governance templates, CI/CD pipelines, and development tooling for any project
2. ATOM+SAGE Framework: Intent-driven operations with validated 7-minute crash recovery

Both are fully open source (MIT licensed) and designed for professional deployment.

# Clone repository
git clone https://github.com/toolate28/kenl.git
cd kenl

# Bootstrap development environment
./scripts/bootstrap.sh

# OPTIONAL: Install ATOM+SAGE framework
cd atom-sage-framework
./install.sh

Professional-grade templates and automation for:

• Governance: ARCREF (architectural reference artifacts) + ADR (decision records)
• CI/CD: GitHub Actions with pre-commit hooks, CodeQL security scanning
• Templates: Issue templates, PR templates, contribution guidelines
• Security: Dependabot, secret detection, security policy
• Documentation: Metadata standards, OWI framework documentation

Use this to: Bootstrap new projects with enterprise-grade governance and automation.

Intent-driven operations with proven crash recovery:

• 7-minute recovery: Validated real-world recovery from catastrophic failures
• 100% intent preservation: Full context reconstruction from minimal input
• Zero dependencies: Pure POSIX shell core
• Self-validating: CTFWI methodology for AI assistant validation

Use this to: Make all operations traceable, all crashes recoverable.

Location: ./atom-sage-framework/ - Read more →

kenl implements a dual-documentation governance pattern:

File: mcp-governance/ARCREF_TEMPLATE.yaml

Structured format for infrastructure/architecture decisions:

• Technical specifications with rollback plans
• Test verification and dependencies
• Migration steps and monitoring

When to use: MCP changes, cloud deployments, platform upgrades, repository-level infrastructure

File: 02-Decisions/ADR_TEMPLATE.md

Narrative format for decision documentation:

• Context and problem statement
• Decision rationale and consequences
• Links to ARCREF artifacts

When to use: Major architectural decisions, technology choices, process changes

See ARCREF::BWI::ATOM-SAGE::001 + ADR-001 for the ATOM+SAGE framework launch - demonstrates the governance pattern in action.

Captures why operations happen (not just what), enabling:

• 85% faster recovery: 7 minutes vs 30-60 minutes traditional
• 87% less input: 147 characters vs ~1,200 characters required
• Minimal user burden: "Continue from crash" is sufficient input
• Complete context: Reconstructs all parallel workflows automatically

Scenario: Complete system crash during Bazzite Linux configuration

• Lost: 4 concurrent Claude Code conversations
• User input: 147 characters (fits in half a tweet)
• Recovery time: 7 minutes
• Result: 100% context restored, all tasks completed

Read full validation case study →

# Create traceable operations
atom STATUS "Starting database migration project"
atom CFG "Configure PostgreSQL connection pool"
atom DEV "Implement user authentication module"
atom TASK "TODO: Add rate limiting"

# After crash: Instant recovery
atom-analytics --recovery
# Shows: all 4 contexts, pending tasks, last status, next action

ATOM-SEC: AI security testing with forensic audit trails ATOM-GOV: MCP governance with policy-as-code ATOM-EOL: Windows 10 EOL migration framework

Explore all applications →

kenl/
├── atom-sage-framework/          # Intent-driven operations framework
│   ├── README.md                 # Framework documentation
│   ├── install.sh                # Zero-dependency installer
│   ├── docs/                     # Guides and validation studies
│   ├── examples/                 # Runnable demonstrations
│   ├── analytics/                # Advanced analysis tools
│   └── forks/                    # Specialized applications
│       ├── ATOM-SEC/             # AI security & red-teaming
│       ├── ATOM-GOV/             # MCP governance
│       └── ATOM-EOL/             # Windows 10 EOL migration
├── mcp-governance/               # ARCREF artifacts
│   ├── ARCREF_TEMPLATE.yaml      # Template for new artifacts
│   └── ARCREF-ATOM-SAGE-001.yaml # Example: ATOM+SAGE launch
├── 02-Decisions/                 # ADR documents
│   ├── ADR_TEMPLATE.md           # Template for new decisions
│   └── ADR-001-ATOM-SAGE-LAUNCH.md # Example: ATOM+SAGE decision
├── scripts/                      # Automation and tooling
│   ├── bootstrap.sh              # Development environment setup
│   ├── add-owi-metadata.sh       # Documentation metadata
│   └── owi-report.sh             # Documentation index generation
├── .github/                      # GitHub automation
│   ├── workflows/                # CI/CD pipelines
│   └── ISSUE_TEMPLATE/           # Issue templates
├── CONTRIBUTING.md               # Contribution guidelines
├── SECURITY.md                   # Security policy
└── README.md                     # This file

1. Fork and clone the repository

2. Create a branch following naming conventions:

   • feat/description - New features
   • fix/description - Bug fixes
   • docs/description - Documentation
   • refactor/description - Code refactoring

3. Make changes with proper commit messages:

   type: subject line
   
   Body with details
   
   ATOM-TYPE-YYYYMMDD-NNN
   

   Types: feat, fix, docs, refactor, test, chore

4. Run pre-commit checks:

   pre-commit run --all-files

5. Create pull request with:

   • Clear description
   • ARCREF + ADR for architectural changes
   • Tests and documentation updates

See CONTRIBUTING.md for detailed guidelines.

For infrastructure, MCP, or architectural changes:

1. Create ARCREF artifact in mcp-governance/
2. Create ADR document in 02-Decisions/
3. Link them bidirectionally
4. Include rollback plan and tests
5. Reference in PR description

Example: See ARCREF-ATOM-SAGE-001.yaml + ADR-001-ATOM-SAGE-LAUNCH.md

To bootstrap a new project with kenl's governance infrastructure:

# Option 1: Fork this repository
# Option 2: Extract scaffold
./make_kenl_scaffold_zip.sh
# Creates kenl-scaffold.zip with clean template structure

To add intent-driven operations to your workflow:

cd atom-sage-framework
./install.sh

# Start using
atom STATUS "Your first traceable operation"
atom-analytics --summary

Complete getting started guide →

• CLAUDE.md: Guidance for Claude Code instances
• OWI Framework: Complete methodology specification
• OWI Metadata Standard: Documentation system

• Framework README: Overview and quick start
• Validation Study: 7-minute recovery forensics
• Getting Started: 15-minute tutorial

• ARCREF-ATOM-SAGE-001: Technical specification
• ADR-001: Decision narrative

.github/workflows/ci.yml: Continuous integration

• Pre-commit hooks (trailing whitespace, YAML validation, secrets detection)
• CodeQL security analysis (JavaScript, Python)
• Automated testing (pytest when tests exist)

.github/workflows/release.yml: Release automation

• Semantic versioning
• Automated changelog generation
• Triggered on version tags (v*.*.*)

Enforced on every commit:

• Trailing whitespace removal
• End-of-file fixers
• YAML/JSON validation
• Large file detection
• Secret detection (detect-secrets)
• Shellcheck for bash scripts

Run manually:

pre-commit run --all-files

• Issues: GitHub Issues for bugs and feature requests
• Discussions: GitHub Discussions for questions
• Pull Requests: Contributions welcome! See CONTRIBUTING.md
• Security: Report vulnerabilities per SECURITY.md

kenl is part of the Bazza-DX ecosystem focused on gaming-with-intent on immutable Linux systems:

• Base: Bazzite-DX (Fedora Atomic/rpm-ostree)
• Gaming: Proton/GE-Proton, GameScope, MangoHud
• Dev: KENL distrobox (Ubuntu 24.04 + Claude Code)
• Cloud: Cloudflare Workers/D1/KV/R2
• Methodology: OWI Framework (Gaming-With-Intent, Configuring-With-Intent, Building-With-Intent)

Target use case: Windows 10 EOL migration (Oct 2025) providing evidence-based, rollback-safe gaming configurations.

MIT License - see LICENSE for details.

Both the scaffold and ATOM+SAGE framework are fully open source.

• OWI Framework: Methodology for transparent, traceable system development
• SAGE Framework: System-Aware Guided Evolution principles
• Community: Contributors and early adopters

Version: 1.0.0 Status: Production Ready Last Updated: 2025-11-06 ATOM: ATOM-DOC-20251107-014