From 62b7570ee8150781e5a99757c35f54f1f91df97a Mon Sep 17 00:00:00 2001 From: Kim Harjamaki Date: Fri, 3 Jul 2026 06:07:49 +0300 Subject: [PATCH 01/11] test: verify GitHub write access --- docs/ai/test-connector-cleanup.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 docs/ai/test-connector-cleanup.md diff --git a/docs/ai/test-connector-cleanup.md b/docs/ai/test-connector-cleanup.md new file mode 100644 index 0000000..35686ed --- /dev/null +++ b/docs/ai/test-connector-cleanup.md @@ -0,0 +1,3 @@ +# Connector test + +This file verifies write access and should be removed before final PR. From 22f51d9a94a54125d1560799906878703aeeba39 Mon Sep 17 00:00:00 2001 From: Kim Harjamaki Date: Fri, 3 Jul 2026 06:07:58 +0300 Subject: [PATCH 02/11] test: remove connector write access check --- docs/ai/test-connector-cleanup.md | 3 --- 1 file changed, 3 deletions(-) delete mode 100644 docs/ai/test-connector-cleanup.md diff --git a/docs/ai/test-connector-cleanup.md b/docs/ai/test-connector-cleanup.md deleted file mode 100644 index 35686ed..0000000 --- a/docs/ai/test-connector-cleanup.md +++ /dev/null @@ -1,3 +0,0 @@ -# Connector test - -This file verifies write access and should be removed before final PR. From df0c5474c6c609ce6d3e0d86175383dee4f0305e Mon Sep 17 00:00:00 2001 From: Kim Harjamaki Date: Fri, 3 Jul 2026 06:08:35 +0300 Subject: [PATCH 03/11] docs: add AI Engineering Operating System readme --- docs/ai-engineering-operating-system/README.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 docs/ai-engineering-operating-system/README.md diff --git a/docs/ai-engineering-operating-system/README.md b/docs/ai-engineering-operating-system/README.md new file mode 100644 index 0000000..80438ae --- /dev/null +++ b/docs/ai-engineering-operating-system/README.md @@ -0,0 +1,5 @@ +# AI Engineering Operating System + +Reusable SDLC loop framework for AI coding agents. + +See ai-engineering-operating-system.md, loop-catalog.md and verifier-catalog.md. From 39ef804857fba1a0dce12de4d6f4cff8761dac82 Mon Sep 17 00:00:00 2001 From: Kim Harjamaki Date: Fri, 3 Jul 2026 06:09:12 +0300 Subject: [PATCH 04/11] docs: add AI Engineering Operating System core spec --- .../ai-engineering-operating-system.md | 67 +++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 docs/ai-engineering-operating-system/ai-engineering-operating-system.md diff --git a/docs/ai-engineering-operating-system/ai-engineering-operating-system.md b/docs/ai-engineering-operating-system/ai-engineering-operating-system.md new file mode 100644 index 0000000..5581523 --- /dev/null +++ b/docs/ai-engineering-operating-system/ai-engineering-operating-system.md @@ -0,0 +1,67 @@ +# AI Engineering Operating System v3.0 + +This document defines a reusable working model for AI coding agents. + +## Master instruction + +```text +You are a senior software engineering agent operating through a deterministic SDLC loop. + +For every task: +1. Understand the goal. +2. Discover repository context. +3. Analyze impact. +4. Plan small reversible steps. +5. Design the simplest safe solution. +6. Review risk. +7. Implement one increment at a time. +8. Self-review. +9. Verify with tools. +10. Review security and performance. +11. Update documentation. +12. Update project memory. +13. Stop only when the Definition of Done passes. + +Never claim success without verification evidence. +Never overwrite user changes. +Never skip planning or verification. +If verification fails, return to the earliest failing phase and continue. +If an action is risky or irreversible, request human approval. +``` + +## State machine + +```mermaid +flowchart TD + A[Understand] --> B[Discover] + B --> C[Analyze] + C --> D[Plan] + D --> E[Design] + E --> F[Risk Review] + F --> G[Implement] + G --> H[Self Review] + H --> I[Verify] + I --> J{Passed?} + J -- No --> K[Diagnose] + K --> C + J -- Yes --> L[Document] + L --> M[Update Memory] + M --> N[Done] +``` + +## Definition of Done + +A task is complete only when: + +- goal achieved +- acceptance criteria satisfied +- applicable tests pass +- build/lint/typecheck are clean when available +- documentation is updated when behavior changes +- security and performance were reviewed +- rollback or revert path is known +- no known critical defects remain + +## Evidence rule + +Every final answer must state what was verified. If a command was not run, say so clearly. From 5c0d8aa6485bece2d6fc6c768d4e825687e6e300 Mon Sep 17 00:00:00 2001 From: Kim Harjamaki Date: Fri, 3 Jul 2026 06:09:20 +0300 Subject: [PATCH 05/11] docs: add AI loop catalog --- .../loop-catalog.md | 57 +++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 docs/ai-engineering-operating-system/loop-catalog.md diff --git a/docs/ai-engineering-operating-system/loop-catalog.md b/docs/ai-engineering-operating-system/loop-catalog.md new file mode 100644 index 0000000..27ec8f7 --- /dev/null +++ b/docs/ai-engineering-operating-system/loop-catalog.md @@ -0,0 +1,57 @@ +# Loop Catalog + +## Universal Loop + +```mermaid +flowchart TD + G[Goal] --> A[Analyze] + A --> P[Plan] + P --> I[Implement] + I --> V[Verify] + V --> Q{Verifier Passed?} + Q -- No --> D[Diagnose Failure] + D --> A + Q -- Yes --> C{Goal Met?} + C -- No --> P + C -- Yes --> Done[Done] +``` + +## Feature Loop + +Goal → user story → acceptance criteria → design → implement → tests → docs → CI → done. + +Verifier: acceptance criteria pass, tests pass, no regression. + +## Bug Fix Loop + +Bug report → reproduce → failing test → root cause → minimal fix → regression tests → done. + +Rule: do not patch symptoms when root cause can be found. + +## Refactoring Loop + +Baseline → characterization tests → small refactor → verify → repeat → done. + +Rule: no behavior change unless explicitly requested. + +## CI/CD Repair Loop + +CI failure → logs → classify failure → root cause → minimal patch → verify locally → PR → done. + +Failure classes: dependency, test, lint, build, environment, flaky test, timeout, permission, secret/config. + +## Infrastructure Loop + +Goal → validate → plan → policy review → approval if risky → apply to dev/test → smoke test → promote. + +Rule: no destructive infrastructure changes without approval. + +## Security Loop + +Threat → control → test → abuse case → fix → verify → document residual risk. + +## Performance Loop + +Measure → bottleneck → hypothesis → change → benchmark → compare → keep or rollback. + +Rule: do not optimize without measurement. From 60eb2ead73fdcca24b680267389357411281e017 Mon Sep 17 00:00:00 2001 From: Kim Harjamaki Date: Fri, 3 Jul 2026 06:09:32 +0300 Subject: [PATCH 06/11] docs: add verifier catalog --- .../verifier-catalog.md | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 docs/ai-engineering-operating-system/verifier-catalog.md diff --git a/docs/ai-engineering-operating-system/verifier-catalog.md b/docs/ai-engineering-operating-system/verifier-catalog.md new file mode 100644 index 0000000..0e1b456 --- /dev/null +++ b/docs/ai-engineering-operating-system/verifier-catalog.md @@ -0,0 +1,37 @@ +# Verifier Catalog + +A verifier proves progress. + +## Strong verifiers + +- build +- typecheck +- unit tests +- integration tests +- smoke tests +- formatter +- linter +- static analysis +- dependency audit +- container build +- infrastructure validation +- deployment health check +- benchmark + +## Weak verifiers + +- self review +- checklist +- code reading + +## Record format + +```text +Verifier: +Command: +Result: +Evidence: +Failures: +Fix: +Final status: +``` From 05750bde249c0b645541b1757ed9ba2f39a5afb6 Mon Sep 17 00:00:00 2001 From: Kim Harjamaki Date: Fri, 3 Jul 2026 06:09:43 +0300 Subject: [PATCH 07/11] docs: add model routing policy --- .../model-routing.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 docs/ai-engineering-operating-system/model-routing.md diff --git a/docs/ai-engineering-operating-system/model-routing.md b/docs/ai-engineering-operating-system/model-routing.md new file mode 100644 index 0000000..0c3b58d --- /dev/null +++ b/docs/ai-engineering-operating-system/model-routing.md @@ -0,0 +1,20 @@ +# Model Routing + +Use cheaper and local models first. Escalate only when confidence is low or risk is high. + +| Work type | Model class | +|---|---| +| File search | local or small | +| Summaries | local or small | +| Boilerplate | local or small | +| Test generation | medium | +| CI log review | medium | +| Bug diagnosis | medium or strong | +| Architecture | strong | +| Final acceptance | strong | + +Rule: + +```text +cheap first -> verify -> escalate only when needed +``` From e5be20f7872be15fda3310d5eb1fe502d0fe49ac Mon Sep 17 00:00:00 2001 From: Kim Harjamaki Date: Fri, 3 Jul 2026 06:09:56 +0300 Subject: [PATCH 08/11] docs: add memory notes --- docs/ai-engineering-operating-system/memory.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 docs/ai-engineering-operating-system/memory.md diff --git a/docs/ai-engineering-operating-system/memory.md b/docs/ai-engineering-operating-system/memory.md new file mode 100644 index 0000000..a61b12b --- /dev/null +++ b/docs/ai-engineering-operating-system/memory.md @@ -0,0 +1,3 @@ +# Memory + +Store decisions, lessons and reusable patterns here. From e44ff11c958cce9f15f0dac9a6b914a020162db6 Mon Sep 17 00:00:00 2001 From: Kim Harjamaki Date: Fri, 3 Jul 2026 06:10:05 +0300 Subject: [PATCH 09/11] docs: add AI-OS wiki home --- docs/ai-engineering-operating-system/wiki/Home.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 docs/ai-engineering-operating-system/wiki/Home.md diff --git a/docs/ai-engineering-operating-system/wiki/Home.md b/docs/ai-engineering-operating-system/wiki/Home.md new file mode 100644 index 0000000..b019205 --- /dev/null +++ b/docs/ai-engineering-operating-system/wiki/Home.md @@ -0,0 +1,13 @@ +# AI Engineering Operating System Wiki + +## Pages + +- Operating System: ../ai-engineering-operating-system.md +- Loop Catalog: ../loop-catalog.md +- Verifier Catalog: ../verifier-catalog.md +- Model Routing: ../model-routing.md +- Memory: ../memory.md + +## Core idea + +Prompt once. Loop until verified. Preserve useful context. Improve every cycle. From f382304e59b8c9a601284a2b63482c1ea1e9e9e4 Mon Sep 17 00:00:00 2001 From: Kim Harjamaki Date: Fri, 3 Jul 2026 06:10:10 +0300 Subject: [PATCH 10/11] docs: add ADR template for AI-OS --- .../adr-template.md | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 docs/ai-engineering-operating-system/adr-template.md diff --git a/docs/ai-engineering-operating-system/adr-template.md b/docs/ai-engineering-operating-system/adr-template.md new file mode 100644 index 0000000..834372f --- /dev/null +++ b/docs/ai-engineering-operating-system/adr-template.md @@ -0,0 +1,21 @@ +# ADR-0000: Title + +## Status + +Proposed / Accepted / Superseded + +## Context + +What problem required a decision? + +## Decision + +What did we decide? + +## Alternatives Considered + +## Consequences + +## Rollback + +## References From 782a3d22262320d659ab88448b665ad416bab315 Mon Sep 17 00:00:00 2001 From: Kim Harjamaki Date: Fri, 3 Jul 2026 06:10:16 +0300 Subject: [PATCH 11/11] docs: add AI project context template --- .../context-template.md | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 docs/ai-engineering-operating-system/context-template.md diff --git a/docs/ai-engineering-operating-system/context-template.md b/docs/ai-engineering-operating-system/context-template.md new file mode 100644 index 0000000..991fd95 --- /dev/null +++ b/docs/ai-engineering-operating-system/context-template.md @@ -0,0 +1,33 @@ +# Project Context Template + +## Repository Purpose + +TBD + +## Architecture + +TBD + +## Stack + +TBD + +## Build Commands + +TBD + +## Test Commands + +TBD + +## Lint Commands + +TBD + +## Deployment Model + +TBD + +## Human Approval Boundaries + +TBD