{"id":50768780,"url":"https://github.com/stecrin/ai-development-os","last_synced_at":"2026-06-11T16:30:27.516Z","repository":{"id":362771061,"uuid":"1254281869","full_name":"stecrin/ai-development-os","owner":"stecrin","description":"A structured AI-assisted development framework for Claude Code, with roles, memory, safety gates, and human approval workflows.","archived":false,"fork":false,"pushed_at":"2026-06-05T19:57:43.000Z","size":49,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T21:22:47.869Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://stefancringusi.com/pages/ai-development-os.html","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stecrin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY_RULES.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-30T11:22:12.000Z","updated_at":"2026-06-05T19:57:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/stecrin/ai-development-os","commit_stats":null,"previous_names":["stecrin/ai-development-os"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/stecrin/ai-development-os","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stecrin%2Fai-development-os","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stecrin%2Fai-development-os/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stecrin%2Fai-development-os/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stecrin%2Fai-development-os/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stecrin","download_url":"https://codeload.github.com/stecrin/ai-development-os/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stecrin%2Fai-development-os/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34208761,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-11T16:30:21.920Z","updated_at":"2026-06-11T16:30:27.507Z","avatar_url":"https://github.com/stecrin.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Development OS\n\nA human-controlled framework for safe, structured, AI-assisted software development using Claude Code.\n\n---\n\n## Short description\n\nAI Development OS is a global rule and memory system that lives outside any single project. It defines how Claude Code should behave across every project under `~/Projects` — what roles it can take, how it handles memory between sessions, what it needs human approval for, and how it fits into a real Git/GitHub workflow.\n\nIt is not a fully autonomous agent. It is a framework that makes AI-assisted development safer, more repeatable, and easier to pick up after a break.\n\n---\n\n## Why this exists\n\nWorking with Claude Code across multiple projects without a shared structure creates recurring problems:\n\n- Every session starts cold — no memory of what was decided, what branch is active, what the risks are.\n- Without role boundaries, the AI tries to plan, build, test, and deploy all at once.\n- Safety rules (don't touch production data, don't edit `.env`, don't deploy without approval) have to be re-stated in every prompt.\n- Git discipline — branch naming, commit conventions, PR format — drifts unless it's embedded in the rules.\n- There's no clean answer to \"pick up where we left off.\"\n\nThis framework solves those problems once, globally, so they don't need solving per project.\n\n---\n\n## What it does\n\n- Defines a **master framework** with core safety rules, a development workflow, and a human approval system.\n- Provides **specialist rule files** for coding standards, security, deployment, and memory — loaded only when relevant.\n- Provides **agent roles** so planning, building, testing, security review, and deployment review are separated rather than blurred.\n- Provides **project memory files** so context (status, decisions, backlog, summaries) survives between sessions.\n- Provides **templates** so any new project can be connected to the framework in minutes.\n- Enforces **human approval gates** before anything irreversible: commits, deployments, migrations, production changes.\n\n---\n\n## Core components\n\n### Specialist rule files\n\n| File | Purpose |\n|------|---------|\n| [`AUTONOMOUS_DEV_FRAMEWORK.md`](./AUTONOMOUS_DEV_FRAMEWORK.md) | Master index. Core safety rules, workflow, orchestration, AI authority levels, output format. The first file every session reads. |\n| [`AI_AGENT_RULES.md`](./AI_AGENT_RULES.md) | 8 agent roles with missions, activation conditions, outputs, and handoffs. |\n| [`GLOBAL_CODING_STANDARDS.md`](./GLOBAL_CODING_STANDARDS.md) | Code quality: architecture boundaries, safe refactoring, API compatibility, config discipline, logging, performance, generated code, developer handoff. |\n| [`SECURITY_RULES.md`](./SECURITY_RULES.md) | Secrets, production data, input validation, external APIs/webhooks, file uploads, infrastructure, AI-specific security, severity levels. |\n| [`DEPLOYMENT_RULES.md`](./DEPLOYMENT_RULES.md) | Deployment authority, branching, commit gates, migration safety, CI/CD, pre/post-deploy checklists, failed deployment response, rollback. |\n| [`MEMORY_SYSTEM.md`](./MEMORY_SYSTEM.md) | Memory authority order, per-project memory files, lightweight Agile vocabulary, session start/end routines. |\n| [`CONTEXT_MANAGEMENT_RULES.md`](./CONTEXT_MANAGEMENT_RULES.md) | Context hygiene, batch discipline, minimal filesystem access, and prevention of unnecessary repository scans or 1M context usage during routine tasks. |\n\n### Project templates\n\n| Template | Purpose |\n|----------|---------|\n| [`PROJECT_CLAUDE_TEMPLATE.md`](./PROJECT_CLAUDE_TEMPLATE.md) | Copy into a project as `CLAUDE.md`. Points back to this framework. Holds stack, commands, AI authority level, do-not-touch list. |\n| [`PROJECT_ONBOARDING_TEMPLATE.md`](./PROJECT_ONBOARDING_TEMPLATE.md) | Run once when entering a new/unknown project. Covers stack detection, risk scan, memory file check, Agile context. |\n| [`PROJECT_STATUS_TEMPLATE.md`](./PROJECT_STATUS_TEMPLATE.md) | Copy into a project as `PROJECT_STATUS.md`. Updated at the start and end of every session. |\n\n---\n\n## Agent roles\n\nThe framework uses 8 roles, loosely inspired by BMAD-style agent discipline. Each role has a defined mission, activation condition, output, and handoff to the next role. Roles don't blur — an Analyst doesn't write code; a Developer doesn't plan architecture.\n\n| # | Role | When to use |\n|---|------|------------|\n| 1 | **Strategic Advisor** | New feature, direction change, prioritisation, comparing approaches. |\n| 2 | **Analyst** | Unclear scope, entering a new area, inspecting before changing. |\n| 3 | **Product Manager** | Turning a problem into a concrete, testable spec. |\n| 4 | **Architect** | Cross-module changes, data model changes, new dependencies. |\n| 5 | **Developer** | Agreed plan exists, feature branch is ready. |\n| 6 | **QA / Test Architect** | Code is written, before commit — run and write tests. |\n| 7 | **Security Reviewer** | Before commit/PR — always for auth, secrets, data, APIs, infra. |\n| 8 | **DevOps / Deployment Reviewer** | Preparing a commit, PR, or release. |\n\n**Shortened flows** are allowed for low-risk tasks:\n- `Developer → QA` for trivial, well-understood changes.\n- `Analyst → Developer → QA` for small changes needing a quick look first.\n\n**Security Reviewer** can be activated early (before Developer) when the task touches auth, permissions, payments, secrets, or external APIs.\n\nFull role definitions, including handoffs and outputs, are in [`AI_AGENT_RULES.md`](./AI_AGENT_RULES.md).\n\n---\n\n## Workflow layer\n\nThe framework includes a workflow layer that turns common development situations into repeatable, step-by-step operating procedures.\n\nRoles define what Claude can do. Safety gates define what requires human approval. Workflows define the sequence — what to inspect, in what order, with what gates, for a specific situation. Each workflow names a recommended role, includes a gate at every step, and ends with a concrete output the human can review before deciding what happens next.\n\nClaude does not run workflows automatically. A workflow is invoked explicitly, and human approval is required at each gate before proceeding.\n\n| Workflow | Use when |\n|----------|----------|\n| [`workflows/project-inspection.md`](./workflows/project-inspection.md) | You have returned to a project and need to safely recover its current state before doing anything. |\n| [`workflows/pre-commit-review.md`](./workflows/pre-commit-review.md) | You are about to commit and want a structured safety check covering secrets, personal data, branch state, and staged files. |\n| [`workflows/documentation-update.md`](./workflows/documentation-update.md) | You are creating or updating documentation and want a controlled process with source verification and private-data checks. |\n\nSee [`workflows/WORKFLOW_INDEX.md`](./workflows/WORKFLOW_INDEX.md) for the full index, human approval rule, and situation-to-workflow lookup.\n\n---\n\n## Lightweight Agile layer\n\nThe framework includes a minimal Agile vocabulary for tracking work across sessions — no sprints, no ceremonies, no story points unless the project has multiple humans who need them.\n\n| Concept | Meaning |\n|---------|---------|\n| **Epic** | A large outcome being worked toward. |\n| **Story** | A small, executable task. |\n| **Acceptance criteria** | How we know the story is done. |\n| **Backlog** | Prioritised list of work. |\n| **Retrospective** | Learning captured after major milestones. |\n\nEvery next task is defined with: Action, Why it matters, Done when.\n\n---\n\n## Project memory system\n\nPer-project memory files live in the project root and are updated at the end of every session.\n\n| File | Purpose |\n|------|---------|\n| `PROJECT_STATUS.md` | Current phase, branch, last/next task, risks, test/deploy status, AI authority level. |\n| `PROJECT_SUMMARY.md` | Compressed one-page overview for fast context recovery on large projects. |\n| `PROJECT_BACKLOG.md` | Epics, stories, priorities, acceptance criteria. |\n| `DECISION_LOG.md` | Major decisions, rationale, alternatives considered, date. |\n| `RETROSPECTIVE.md` | What worked, what failed, what to change — written after major milestones. |\n\n**Session start:** read `CLAUDE.md` → `PROJECT_STATUS.md` → optionally `PROJECT_SUMMARY.md`, `PROJECT_BACKLOG.md`, `DECISION_LOG.md`.\n\n**Session end:** update `PROJECT_STATUS.md` always; update other files if decisions were made, priorities changed, or a milestone was reached.\n\nMemory authority order (highest wins when sources conflict):\n1. User instruction in the current session\n2. Project `CLAUDE.md`\n3. `PROJECT_STATUS.md`\n4. `DECISION_LOG.md`\n5. README / docs\n6. Global `_AI_RULES`\n\n---\n\n## Safety and human approval gates\n\nThe framework has three layers of safety:\n\n**1. AI authority levels** (set per project in `CLAUDE.md` or `PROJECT_STATUS.md`):\n\n| Level | What Claude may do |\n|-------|-------------------|\n| `read-only` | Inspect and report only. |\n| `propose-only` | Suggest changes; do not apply them. |\n| `may-edit` | Edit files on a feature branch. No commits without approval. |\n| `may-commit` | Edit and commit. No deployment without approval. |\n| `may-deploy-with-approval` | May deploy after explicit human confirmation in the current session. |\n\nProduction deployment always requires explicit human approval in the current session, regardless of authority level.\n\n**2. Safety gates** — stop and provide risk assessment + rollback plan before changing anything in:\nauthentication, authorization, payments, database migrations, production deployment, user data, production data, file uploads, external APIs/webhooks, security policies, permissions, infrastructure, environment variables, secrets, or AI/prompt-injection-sensitive workflows.\n\n**3. Absolute DO NOT list** — enforced regardless of instruction:\n- Never push to `main`/`master` directly.\n- Never deploy to production automatically.\n- Never delete databases, uploads, backups, or user data.\n- Never edit `.env` files or expose secrets.\n- Never rewrite the app from scratch without justification.\n- Never hide uncertainty.\n\n---\n\n## How to connect a new project\n\n1. Copy [`PROJECT_CLAUDE_TEMPLATE.md`](./PROJECT_CLAUDE_TEMPLATE.md) into the project root as `CLAUDE.md` and fill the placeholders.\n2. Run [`PROJECT_ONBOARDING_TEMPLATE.md`](./PROJECT_ONBOARDING_TEMPLATE.md) as an Analyst task to inspect the stack, commands, conventions, and risks.\n3. Copy [`PROJECT_STATUS_TEMPLATE.md`](./PROJECT_STATUS_TEMPLATE.md) into the project root as `PROJECT_STATUS.md`.\n4. Create the other memory files as needed: `PROJECT_SUMMARY.md`, `PROJECT_BACKLOG.md`, `DECISION_LOG.md`.\n5. In each Claude Code session, start by reading `CLAUDE.md` → `PROJECT_STATUS.md`.\n\n---\n\n## Validation status\n\n**First validation project:** LegionTrap TI (`~/Projects/gitrepo/legiontrap-ti`) — 2026-05-30.\n\n### Confirmed working\n- Project onboarding using the framework's templates.\n- Memory file creation: `CLAUDE.md`, `PROJECT_STATUS.md`, `PROJECT_SUMMARY.md`, `PROJECT_BACKLOG.md`, `DECISION_LOG.md`.\n- Analyst role: inspecting `.bak` files, temp files, `node_modules`, `.gitignore`, test event files.\n- Developer role: removing tracked `.bak` files from Git, fixing `.gitignore` conflict residue.\n- Cleanup task: removing `tmp_events_test.jsonl` via a separate approved step.\n- Full PR workflow: `docs/` and `chore/` branches → commits → GitHub PRs → merges into main → branch deletion.\n- Human approval at every stage. No autonomous commits or deployments.\n\n### Still needs validation\n- Strategic Advisor, Architect, QA/Test Architect, Security Reviewer, DevOps Reviewer roles.\n- Feature development, database migrations, deployment pipeline changes.\n- Multi-session memory recovery using `PROJECT_SUMMARY.md`.\n- `DECISION_LOG.md` under a real contested architectural decision.\n- `RETROSPECTIVE.md` after a major milestone.\n- `may-deploy-with-approval` authority level in a real deployment.\n- Conflict resolution between memory sources.\n\nSee [`FRAMEWORK_VALIDATION_LOG.md`](./FRAMEWORK_VALIDATION_LOG.md) for the full validation record.\n\n---\n\n## Current limitations\n\n- The framework has been validated on low-risk tasks only. Feature development and deployment flows are not yet tested.\n- Memory files must be updated manually at session end — there is no automated sync.\n- Roles are enforced by instruction, not by technical isolation. Discipline depends on following the rules.\n- The Agile layer is lightweight by design — not suitable for teams without adaptation.\n- Templates require manual copying and filling per project.\n\n---\n\n## Repository structure\n\n```\n_AI_RULES/\n│\n├── AUTONOMOUS_DEV_FRAMEWORK.md   ← Master index. Start here.\n├── AI_AGENT_RULES.md             ← Agent roles and pipeline\n├── GLOBAL_CODING_STANDARDS.md    ← Code quality rules\n├── SECURITY_RULES.md             ← Security rules and checklist\n├── DEPLOYMENT_RULES.md           ← Deployment authority and gates\n├── MEMORY_SYSTEM.md              ← Memory files and session routines\n│\n├── PROJECT_CLAUDE_TEMPLATE.md    ← Template: project CLAUDE.md\n├── PROJECT_ONBOARDING_TEMPLATE.md ← Template: first-session inspection\n├── PROJECT_STATUS_TEMPLATE.md    ← Template: living status file\n│\n├── FRAMEWORK_VALIDATION_LOG.md   ← Validation history\n├── PORTFOLIO_PROJECT_BRIEF.md    ← Portfolio story and website content\n├── README.md                     ← This file\n│\n├── workflows/                    ← Workflow layer: step-by-step operating procedures\n│   ├── WORKFLOW_INDEX.md         ← Workflow index and human approval rule\n│   ├── project-inspection.md     ← Inspect project state at session start\n│   ├── pre-commit-review.md      ← Safety check before committing\n│   └── documentation-update.md   ← Controlled documentation creation and editing\n│\n└── _backups/                     ← Timestamped backups before edits\n```\n\n---\n\n## Portfolio note\n\nThis project is documented as a portfolio piece in [`PORTFOLIO_PROJECT_BRIEF.md`](./PORTFOLIO_PROJECT_BRIEF.md). It demonstrates:\n\n- Systematic thinking about AI tooling and safe human-AI collaboration.\n- Software engineering process: branching, commit discipline, PR workflow, code review gates.\n- Security awareness: structured handling of secrets, production data, deployment authority.\n- Technical writing: precise, operational documentation that is actively used.\n- Iterative development: built and refined through real use, not written once and shelved.\n\nThe project began from a personal need to work more safely and consistently with Claude Code across multiple projects. Role discipline was later strengthened using BMAD as an inspiration reference. A lightweight Agile layer was added to manage backlog and session continuity.\n\n---\n\n## Next development steps\n\n1. **Validate the Architect + Developer + QA pipeline** on a real feature addition in an active project.\n2. **Exercise the Security Reviewer role** on a change touching auth, API keys, or user data.\n3. **Exercise the DevOps Reviewer role** on a real deployment or CI/CD change.\n4. **Test multi-session recovery** using `PROJECT_SUMMARY.md` across at least two sessions.\n5. **Add remaining templates:** `DECISION_LOG_TEMPLATE.md`, `PROJECT_BACKLOG_TEMPLATE.md`, `PROJECT_SUMMARY_TEMPLATE.md`, `RETROSPECTIVE_TEMPLATE.md`.\n6. **Stress-test `DECISION_LOG.md`** with a real contested architectural decision.\n7. **Validate `may-deploy-with-approval`** on a non-production deployment in a controlled project.\n8. **Consider versioning the framework** (e.g. `v1.0`, `v1.1`) once the full role pipeline has been validated end-to-end.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstecrin%2Fai-development-os","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstecrin%2Fai-development-os","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstecrin%2Fai-development-os/lists"}