diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..4d761dd --- /dev/null +++ b/.editorconfig @@ -0,0 +1,10 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true + +[*.md] +trim_trailing_whitespace = false diff --git a/.github/ISSUE_TEMPLATE/change.yml b/.github/ISSUE_TEMPLATE/change.yml new file mode 100644 index 0000000..c6649d4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/change.yml @@ -0,0 +1,17 @@ +name: Change request +description: Propose a controlled change to AI-OS +title: "[Change]: " +labels: ["change"] +body: + - type: textarea + id: goal + attributes: + label: Goal + validations: + required: true + - type: textarea + id: verification + attributes: + label: Verification + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..7ae27d1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Security report + url: https://github.com/Coding-Autopilot-System/ai-engineering-operating-system/security/advisories/new + about: Report security-sensitive issues privately. diff --git a/.github/ISSUE_TEMPLATE/docs_gap.yml b/.github/ISSUE_TEMPLATE/docs_gap.yml new file mode 100644 index 0000000..24679f4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/docs_gap.yml @@ -0,0 +1,25 @@ +name: Documentation gap +description: Report missing, confusing, or stale documentation +title: "[Docs]: " +labels: ["documentation"] +body: + - type: textarea + id: gap + attributes: + label: Gap + description: What is missing or unclear? + validations: + required: true + - type: textarea + id: location + attributes: + label: Location + description: Link or path if known. + validations: + required: false + - type: textarea + id: done + attributes: + label: Definition of done + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..ef2164e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,25 @@ +name: Feature request +description: Propose a new loop, verifier, prompt, example, or integration +title: "[Feature]: " +labels: ["enhancement"] +body: + - type: textarea + id: goal + attributes: + label: Goal + description: What should improve? + validations: + required: true + - type: textarea + id: plan + attributes: + label: Proposed plan + description: Describe the loop, files, and verification you expect. + validations: + required: true + - type: textarea + id: acceptance + attributes: + label: Acceptance criteria + validations: + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..8a38b97 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,47 @@ +# Summary + +Explain the goal and what changed. + +# Loop used + +- [ ] Feature +- [ ] Bug fix +- [ ] Refactoring +- [ ] CI/CD repair +- [ ] Security +- [ ] Documentation +- [ ] Release +- [ ] Continuous improvement + +# Plan approval + +- [ ] Plan was stated before implementation +- [ ] Human approval was requested where needed +- [ ] No risky or irreversible change was made without approval + +# Verification evidence + +| Gate | Evidence | +|---|---| +| Structure check | | +| Docs check | | +| Mermaid check | | +| Security review | | +| Link check | | + +# Documentation + +- [ ] README updated if needed +- [ ] Docs updated if needed +- [ ] Wiki navigation updated if needed +- [ ] ADR added if needed + +# Risk and rollback + +Risk level: LOW / MEDIUM / HIGH + +Rollback plan: + +# Remaining work + +List anything intentionally left out. diff --git a/.github/dependabot.yaml b/.github/dependabot.yaml new file mode 100644 index 0000000..8e39a40 --- /dev/null +++ b/.github/dependabot.yaml @@ -0,0 +1,10 @@ +version: 2 +updates: +- package-ecosystem: github-actions + directory: / + schedule: + interval: weekly +- package-ecosystem: pip + directory: / + schedule: + interval: weekly diff --git a/.github/workflows/ci-docs.yml b/.github/workflows/ci-docs.yml new file mode 100644 index 0000000..df61a5c --- /dev/null +++ b/.github/workflows/ci-docs.yml @@ -0,0 +1,23 @@ +name: ci-docs + +on: + pull_request: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +jobs: + docs-quality: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + - name: Verify repository structure + run: python scripts/verify_repo.py + - name: Run structure tests + run: python -m pytest tests diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml new file mode 100644 index 0000000..3a48744 --- /dev/null +++ b/.github/workflows/dependency-review.yml @@ -0,0 +1,15 @@ +name: dependency-review + +on: + pull_request: + +permissions: + contents: read + pull-requests: read + +jobs: + dependency-review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/dependency-review-action@v4 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..7a16a37 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,34 @@ +name: release + +on: + workflow_dispatch: + inputs: + version: + description: Semantic version tag such as v1.0.0 + required: true + +permissions: + contents: write + +jobs: + release: + runs-on: ubuntu-latest + environment: release + steps: + - uses: actions/checkout@v4 + - name: Validate version + run: | + python - <<'PY' + import os, re + version = os.environ['VERSION'] + if not re.fullmatch(r'v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?', version): + raise SystemExit('Invalid version: ' + version) + print(version) + PY + env: + VERSION: ${{ inputs.version }} + - name: Create release + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + VERSION: ${{ inputs.version }} + run: gh release create "$VERSION" --title "$VERSION" --generate-notes diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..d7a6aa3 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,5 @@ +{ + "MD013": false, + "MD033": false, + "MD041": true +} diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..30642bd --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,17 @@ +# Changelog + +All notable changes to AI-OS will be documented here. + +The format follows a human-readable release log and versions follow `VERSIONING.md`. + +## Unreleased + +### Added + +- Production-grade governance files. +- Continuous improvement loop documentation. +- Expanded loop, verifier, prompt, wiki, and CI/CD structure. + +### Changed + +- README now positions AI-OS as a loop-engineered, verification-driven operating model. diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 0000000..a49955e --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1,8 @@ +* @ogeonx +/.github/ @ogeonx +/docs/ @ogeonx +/prompts/ @ogeonx +/wiki/ @ogeonx +/adr/ @ogeonx +/scripts/ @ogeonx +/tests/ @ogeonx diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..e2fa036 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,21 @@ +# Code of Conduct + +This project uses a simple professional conduct standard. + +## Expected behavior + +- Be respectful and constructive. +- Focus criticism on ideas, evidence, and implementation quality. +- Prefer clear improvement proposals over vague objections. +- Assume good intent, but verify technical claims. + +## Unacceptable behavior + +- Harassment, threats, or abuse. +- Publishing private information. +- Repeated disruption of technical discussion. +- Attempts to bypass security or approval processes. + +## Enforcement + +Maintainers may edit, close, hide, or remove contributions that violate this standard. Serious issues should be reported through the security or support channels. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..d4eb6ab --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,35 @@ +# Contributing + +AI-OS contributions must improve clarity, safety, repeatability, or verification. + +## Contribution loop + +```mermaid +flowchart TD + Idea[Idea] --> Issue[Open Issue] + Issue --> Plan[Write Plan] + Plan --> Approval{Maintainer Approval Needed?} + Approval -- Yes --> Review[Human Review] + Approval -- No --> Branch[Create Branch] + Review --> Branch + Branch --> Change[Make Small Change] + Change --> Verify[Run Verifiers] + Verify --> Pass{Passed?} + Pass -- No --> Fix[Fix and Re-run] + Fix --> Verify + Pass -- Yes --> PR[Open PR] + PR --> Done[Review and Merge] +``` + +## Required for PRs + +- Clear goal +- Scope and non-goals +- Verification evidence +- Updated docs when behavior changes +- Mermaid diagrams for new workflows +- Human approval for broad governance, release, or security changes + +## Canonical source + +The `/docs` tree is canonical. Wiki pages are curated navigation pages that point back to canonical docs. diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..5ec53c7 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,35 @@ +# Governance + +AI-OS governance is based on explicit goals, human approval gates, verification evidence, and reversible change. + +## Governance loop + +```mermaid +flowchart TD + Proposal[Proposal] --> Impact[Impact Analysis] + Impact --> Risk[Risk Classification] + Risk --> Plan[Implementation Plan] + Plan --> Approval{Human Approval Required?} + Approval -- Yes --> Human[Maintainer Approval] + Approval -- No --> Implement[Implement] + Human --> Implement + Implement --> Verify[Verify] + Verify --> Pass{Pass?} + Pass -- No --> Rework[Rework] + Rework --> Verify + Pass -- Yes --> Record[Record Decision] + Record --> Done[Done] +``` + +## Approval required + +- Release process changes +- Security policy changes +- Governance changes +- Breaking changes to master prompt semantics +- Automation that can mutate repositories +- Anything that increases risk or cost + +## Decision records + +Use ADRs for structural decisions. ADRs must explain context, decision, alternatives, consequences, and rollback. diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000..30e8294 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,22 @@ +# Maintainers + +## Current maintainer + +- @ogeonx + +## Maintainer responsibilities + +- Preserve the canonical AI-OS operating model. +- Review governance, security, release, and master prompt changes. +- Require verification evidence for meaningful PRs. +- Keep `/docs` canonical and wiki pages curated. +- Avoid merging unsafe autonomous-action patterns. + +## Maintainer review checklist + +- Is the goal clear? +- Is the change reversible? +- Are verifiers documented? +- Are diagrams updated? +- Is human approval needed? +- Does the change improve the repo without unnecessary complexity? diff --git a/README.md b/README.md index 833247e..0860128 100644 --- a/README.md +++ b/README.md @@ -4,14 +4,30 @@ AI Engineering Operating System is a public methodology and documentation framework for turning AI coding agents into disciplined software engineering systems. -It defines reusable SDLC loops, Mermaid diagrams, verification gates, model routing, memory rules, and human approval checkpoints for local-first AI development. +It defines reusable SDLC loops, Mermaid diagrams, verification gates, model routing, memory rules, human approval checkpoints, and continuous improvement workflows for local-first AI development. + +## Why this exists + +Most AI coding workflows still behave like ad-hoc chats. AI-OS turns that into an auditable engineering process: + +1. set a clear goal +2. fan out to specialist roles +3. produce a plan +4. ask for human approval when risk is meaningful +5. implement in small reversible steps +6. verify using strong gates +7. update docs, memory, wiki, and roadmap +8. repeat until no valuable improvement remains ## Start here - [Master operating manual](docs/ai-os/master-operating-manual.md) +- [Continuous improvement loop](docs/methodology/continuous-improvement-loop.md) - [Mermaid diagram catalog](docs/diagrams/README.md) - [Loop catalog](docs/loops/README.md) +- [Verification gates](docs/verifiers/README.md) - [Prompt templates](prompts/README.md) +- [ChatGPT web operating prompt](prompts/chatgpt-web.md) - [Wiki home](wiki/Home.md) ## Everyday prompt @@ -24,14 +40,22 @@ Task: Load context first. Select the right loop. -Plan before implementation. +Fan out analysis to specialist roles. +Create a plan before implementation. +Ask for human approval before risky or broad changes. +Implement approved work in small reversible steps. Verify before declaring completion. Return to the earliest failing phase when verification fails. +Update docs and memory. Stop only when the Definition of Done passes. ``` ## Repository purpose -This repository documents the instructions, diagrams, and operating model I use when working with AI coding agents. +This repository documents the instructions, diagrams, and operating model I use when working with AI coding agents and ChatGPT web sessions. The goal is to make AI-assisted development visible, repeatable, auditable, and production-oriented. + +## Current maturity target + +AI-OS is moving from methodology showcase to production-grade open framework. The next milestones are governance, full wiki, CI quality gates, security posture, release process, examples, and self-improvement automation. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..9d294dd --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,32 @@ +# Security Policy + +AI-OS includes guidance for autonomous and semi-autonomous coding agents. Security reports may include documentation issues, unsafe workflow patterns, prompt-injection risks, tool-use escalation, secret exposure, or CI/CD risk. + +## Report privately + +Use GitHub private vulnerability reporting where available. + +## Scope + +- AI agent instructions that could encourage unsafe actions +- Tool-use escalation risks +- Prompt-injection or context-poisoning risks +- Workflow permissions and CI/CD safety +- Secrets or credential exposure +- Release, approval, or governance bypasses + +## Security review loop + +```mermaid +flowchart TD + Report[Report] --> Triage[Triage] + Triage --> Repro[Reproduce or Validate] + Repro --> Risk[Risk Class] + Risk --> Fix[Fix Plan] + Fix --> Approval{Approval Needed?} + Approval -- Yes --> Human[Maintainer Approval] + Approval -- No --> Patch[Patch] + Human --> Patch + Patch --> Verify[Verify] + Verify --> Publish[Advisory or Changelog] +``` diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..5e4a239 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,18 @@ +# Support + +AI-OS is a public methodology and documentation framework. + +## Best support channels + +- Use GitHub issues for documentation gaps, loop improvements, prompt improvements, and examples. +- Use pull requests for concrete improvements. +- Use private security reporting for vulnerabilities or unsafe autonomous-agent behavior. + +## What to include + +- Goal +- Current behavior +- Desired behavior +- Suggested loop or verifier +- Acceptance criteria +- Verification evidence if available diff --git a/VERSIONING.md b/VERSIONING.md new file mode 100644 index 0000000..33df071 --- /dev/null +++ b/VERSIONING.md @@ -0,0 +1,35 @@ +# Versioning + +AI-OS uses Semantic Versioning for public releases. + +## Version format + +```text +vMAJOR.MINOR.PATCH +``` + +## Meaning + +- MAJOR: breaking change to the operating model, prompt contract, or public structure +- MINOR: new loops, prompts, verifiers, examples, or diagrams +- PATCH: corrections, clarifications, small documentation fixes + +## Release loop + +```mermaid +stateDiagram-v2 + [*] --> ScopeFreeze + ScopeFreeze --> Verify + Verify --> HumanApproval + HumanApproval --> Tag: approved + HumanApproval --> Rework: rejected + Rework --> Verify + Tag --> ReleaseNotes + ReleaseNotes --> Publish + Publish --> PostReleaseCheck + PostReleaseCheck --> [*] +``` + +## Human approval + +All releases require explicit maintainer approval. diff --git a/adr/0000-template.md b/adr/0000-template.md new file mode 100644 index 0000000..584bb99 --- /dev/null +++ b/adr/0000-template.md @@ -0,0 +1,37 @@ +# ADR-0000: Title + +## Status + +Proposed / Accepted / Superseded + +## Context + +What problem required a decision? + +## Decision + +What did we decide? + +## Alternatives considered + +- Option A +- Option B +- Option C + +## Consequences + +Positive: + +- + +Negative: + +- + +## Security impact + +## Operational impact + +## Rollback + +## References diff --git a/docs/ai-os/master-operating-manual.md b/docs/ai-os/master-operating-manual.md index 993b29a..d4a10b0 100644 --- a/docs/ai-os/master-operating-manual.md +++ b/docs/ai-os/master-operating-manual.md @@ -10,19 +10,21 @@ Every task follows this sequence: 1. load context 2. understand goal -3. discover existing system -4. analyze impact -5. plan small reversible steps -6. design the simplest safe solution -7. review risk -8. implement incrementally -9. self-review -10. verify with tools -11. review security and performance -12. update documentation -13. update memory -14. run retrospective -15. stop only when done +3. fan out to specialist reviewers +4. discover existing system +5. analyze impact +6. create a plan before implementation +7. ask for human approval when scope or risk requires it +8. design the simplest safe solution +9. implement incrementally +10. self-review +11. verify with tools +12. review security and performance +13. update documentation and wiki navigation +14. update memory +15. run retrospective +16. repeat until no valuable improvement remains in scope +17. stop only when done ## Master state machine @@ -30,23 +32,40 @@ Every task follows this sequence: stateDiagram-v2 [*] --> Bootstrap Bootstrap --> Understand - Understand --> Discover + Understand --> FanOut + FanOut --> Discover Discover --> Analyze Analyze --> Plan - Plan --> Design + Plan --> HumanApproval: broad or risky + Plan --> Design: low risk + HumanApproval --> Design: approved + HumanApproval --> Replan: rejected or revise + Replan --> Plan Design --> RiskReview RiskReview --> Implement Implement --> SelfReview SelfReview --> Verify Verify --> Document: passed - Verify --> Diagnose: failed + Verify --> Diagnose: not passed Diagnose --> Analyze - Document --> UpdateMemory + Document --> UpdateWiki + UpdateWiki --> UpdateMemory UpdateMemory --> Retrospective - Retrospective --> Done + Retrospective --> MoreValue + MoreValue --> Plan: valuable improvement remains + MoreValue --> Done: complete Done --> [*] ``` +## Fan-out roles + +- Planner: steps, scope, dependencies, rollback +- Architect: system fit and long-term shape +- Security reviewer: trust boundaries and approval gates +- Verifier: tests, checks, evidence +- Documentation reviewer: docs, wiki, examples, changelog +- Maintainer: governance and release implications + ## Definition of Done A task is complete only when: @@ -58,6 +77,7 @@ A task is complete only when: - security reviewed - performance reviewed - documentation updated when needed +- wiki navigation updated when public docs changed - rollback path known - no known critical defect remains @@ -72,6 +92,9 @@ Request approval before: - secret rotation - cost-increasing infrastructure - public release +- governance change +- broad repository restructuring +- automation that mutates repositories ## Final response format @@ -81,6 +104,7 @@ Every final report must include: 2. plan 3. changes 4. verification evidence -5. risks -6. remaining work -7. final status +5. security and risk review +6. documentation and memory updates +7. remaining work +8. final status diff --git a/docs/architecture/fan-out-fan-in.md b/docs/architecture/fan-out-fan-in.md new file mode 100644 index 0000000..2f2b7d8 --- /dev/null +++ b/docs/architecture/fan-out-fan-in.md @@ -0,0 +1,37 @@ +# Fan-out and Fan-in Orchestration + +AI-OS uses specialist roles to reduce blind spots. + +## Pattern + +```mermaid +flowchart LR + Goal[Goal] --> Orchestrator[Orchestrator] + Orchestrator --> Planner[Planner] + Orchestrator --> Architect[Architect] + Orchestrator --> Security[Security] + Orchestrator --> Tester[Tester] + Orchestrator --> Writer[Writer] + Planner --> Merge[Fan-in synthesis] + Architect --> Merge + Security --> Merge + Tester --> Merge + Writer --> Merge + Merge --> Plan[Plan] + Plan --> Human{Human review?} + Human -- Yes --> Approval[Approval] + Human -- No --> Execute[Execute] + Approval --> Execute +``` + +## Roles + +- Planner: scope, steps, dependencies, risks +- Architect: system fit, interfaces, long-term shape +- Security: threat model and approval gates +- Tester: verifiers and evidence +- Writer: docs, examples, wiki, changelog + +## Rule + +The final plan must synthesize all specialist outputs into one coherent path. Disagreements should be documented as tradeoffs. diff --git a/docs/ci-cd/branch-and-tag-rules.md b/docs/ci-cd/branch-and-tag-rules.md new file mode 100644 index 0000000..cce3004 --- /dev/null +++ b/docs/ci-cd/branch-and-tag-rules.md @@ -0,0 +1,35 @@ +# Branch and Tag Rules + +This repository should protect the public operating model through rulesets. + +## Recommended `main` rules + +- require pull request before merge +- require status checks +- require CODEOWNERS review when available +- block force pushes +- block deletion +- keep history linear if desired + +## Recommended tag rules + +- protect `v*` release tags +- block tag deletion +- block tag force updates +- require release workflow for public releases + +## Approval flow + +```mermaid +flowchart TD + PR[Pull Request] --> Checks[Required checks] + Checks --> Review[Review] + Review --> Merge{Merge allowed?} + Merge -- No --> Rework[Rework] + Rework --> Checks + Merge -- Yes --> Main[main] + Main --> Tag{Release?} + Tag -- Yes --> Approval[Release approval] + Tag -- No --> Done[Done] + Approval --> Release[Release] +``` diff --git a/docs/ci-cd/release-process.md b/docs/ci-cd/release-process.md new file mode 100644 index 0000000..81d62db --- /dev/null +++ b/docs/ci-cd/release-process.md @@ -0,0 +1,29 @@ +# Release Process + +AI-OS releases are public signals of methodology stability. + +## Process + +1. Freeze scope. +2. Run full verification. +3. Update changelog. +4. Request human approval. +5. Create SemVer tag. +6. Generate release notes. +7. Validate published links. + +## Mermaid + +```mermaid +stateDiagram-v2 + [*] --> Freeze + Freeze --> Verify + Verify --> Approval + Approval --> Tag: approved + Approval --> Rework: rejected + Rework --> Verify + Tag --> Notes + Notes --> Publish + Publish --> Validate + Validate --> [*] +``` diff --git a/docs/loops/bugfix-loop.md b/docs/loops/bugfix-loop.md new file mode 100644 index 0000000..0a49b90 --- /dev/null +++ b/docs/loops/bugfix-loop.md @@ -0,0 +1,19 @@ +# Bug Fix Loop + +```mermaid +flowchart TD + A[Bug report] --> B[Reproduce] + B --> C[Test case] + C --> D[Cause analysis] + D --> E[Small correction] + E --> F[Regression check] + F --> G{OK?} + G -- No --> D + G -- Yes --> H[Done] +``` + +## Rules + +- Reproduce before changing when possible. +- Prefer a test case that proves the correction. +- Keep the correction minimal. diff --git a/docs/loops/feature.md b/docs/loops/feature.md new file mode 100644 index 0000000..915db3a --- /dev/null +++ b/docs/loops/feature.md @@ -0,0 +1,25 @@ +# Feature Development Loop + +```mermaid +flowchart TD + Goal[Feature goal] --> Value[User value] + Value --> AC[Acceptance criteria] + AC --> Context[Inspect existing patterns] + Context --> Plan[Plan small increments] + Plan --> Implement[Implement increment] + Implement --> Test[Run tests] + Test --> Pass{Pass?} + Pass -- No --> Diagnose[Diagnose] + Diagnose --> Implement + Pass -- Yes --> Docs[Update docs] + Docs --> Done[Done] +``` + +## Required outputs + +- user story +- acceptance criteria +- affected files +- test plan +- verification evidence +- documentation update diff --git a/docs/loops/iac.md b/docs/loops/iac.md new file mode 100644 index 0000000..de09895 --- /dev/null +++ b/docs/loops/iac.md @@ -0,0 +1,24 @@ +# Infrastructure as Code Loop + +```mermaid +flowchart TD + Goal[Infra goal] --> Plan[Plan] + Plan --> Validate[Validate syntax] + Validate --> Preview[Plan or what-if] + Preview --> Risk[Risk and cost review] + Risk --> Approval{Approval needed?} + Approval -- Yes --> Human[Human approval] + Approval -- No --> ApplyDev[Apply to dev or test] + Human --> ApplyDev + ApplyDev --> Smoke[Smoke check] + Smoke --> Promote{Promote?} + Promote -- No --> Rollback[Rollback] + Promote -- Yes --> Done[Done] +``` + +## Approval required + +- production change +- destructive change +- identity or permission change +- cost increase diff --git a/docs/loops/performance.md b/docs/loops/performance.md new file mode 100644 index 0000000..4f2454d --- /dev/null +++ b/docs/loops/performance.md @@ -0,0 +1,22 @@ +# Performance Loop + +```mermaid +flowchart TD + Baseline[Measure baseline] --> Bottleneck[Find bottleneck] + Bottleneck --> Hypothesis[Hypothesis] + Hypothesis --> Change[Change one variable] + Change --> Benchmark[Benchmark] + Benchmark --> Compare[Compare] + Compare --> Keep{Improved enough?} + Keep -- No --> Rollback[Rollback] + Keep -- Yes --> Document[Document result] + Rollback --> Hypothesis + Document --> Done[Done] +``` + +## Rules + +- Do not optimize without measurement. +- Change one thing at a time. +- Keep correctness checks running. +- Document the tradeoff. diff --git a/docs/loops/pipeline-repair.md b/docs/loops/pipeline-repair.md new file mode 100644 index 0000000..026149a --- /dev/null +++ b/docs/loops/pipeline-repair.md @@ -0,0 +1,29 @@ +# Pipeline Repair Loop + +```mermaid +flowchart TD + A[Pipeline not green] --> B[Read logs] + B --> C[Classify] + C --> D[Cause] + D --> E[Small patch] + E --> F[Local check] + F --> G[Pipeline check] + G --> H{Green?} + H -- No --> B + H -- Yes --> I[Done] +``` + +## Classes + +- build +- lint +- test +- dependency +- environment +- permission +- timeout +- configuration + +## Evidence + +Record the job name, cause, files changed, and verification result. diff --git a/docs/loops/refactoring.md b/docs/loops/refactoring.md new file mode 100644 index 0000000..bced063 --- /dev/null +++ b/docs/loops/refactoring.md @@ -0,0 +1,21 @@ +# Refactoring Loop + +```mermaid +flowchart TD + A[Baseline] --> B[Characterization checks] + B --> C[Small refactor] + C --> D[Verify behavior] + D --> E{Same behavior?} + E -- No --> F[Rollback or correct] + F --> C + E -- Yes --> G{More value?} + G -- Yes --> C + G -- No --> H[Done] +``` + +## Rules + +- Do not change behavior unless requested. +- Establish a baseline first. +- Make one small transformation at a time. +- Stop when risk grows faster than value. diff --git a/docs/loops/release.md b/docs/loops/release.md new file mode 100644 index 0000000..e5df32d --- /dev/null +++ b/docs/loops/release.md @@ -0,0 +1,23 @@ +# Release Loop + +```mermaid +stateDiagram-v2 + [*] --> ScopeFreeze + ScopeFreeze --> FullVerify + FullVerify --> HumanApproval + HumanApproval --> Rework: rejected + Rework --> FullVerify + HumanApproval --> Tag: approved + Tag --> ReleaseNotes + ReleaseNotes --> Publish + Publish --> PostReleaseCheck + PostReleaseCheck --> [*] +``` + +## Release requirements + +- version follows `VERSIONING.md` +- changelog updated +- docs checks pass +- release workflow uses a human approval gate +- generated release notes reviewed diff --git a/docs/loops/security.md b/docs/loops/security.md new file mode 100644 index 0000000..7349acf --- /dev/null +++ b/docs/loops/security.md @@ -0,0 +1,23 @@ +# Security Review Loop + +```mermaid +flowchart TD + Asset[Asset] --> Boundary[Trust boundary] + Boundary --> Threat[Threat model] + Threat --> Control[Control] + Control --> Check[Abuse-case check] + Check --> Pass{Blocked?} + Pass -- No --> Improve[Improve control] + Improve --> Check + Pass -- Yes --> Residual[Record residual risk] + Residual --> Done[Done] +``` + +## Required outputs + +- asset +- trust boundary +- likely threats +- control +- verification +- residual risk diff --git a/docs/memory/project-memory.md b/docs/memory/project-memory.md new file mode 100644 index 0000000..70b8b23 --- /dev/null +++ b/docs/memory/project-memory.md @@ -0,0 +1,35 @@ +# Project Memory + +Project memory captures decisions, reusable patterns, and lessons. + +## Memory update loop + +```mermaid +flowchart TD + Change[Significant change] --> Classify[Classify memory value] + Classify --> Update[Update memory file] + Update --> Link[Link related docs or ADR] + Link --> Verify[Verify links] + Verify --> Done[Done] +``` + +## Record format + +```markdown +## YYYY-MM-DD - Title + +Decision: +Context: +Consequences: +Related files: +Verification: +Next improvement: +``` + +## When to update + +- operating model changes +- new loop or verifier +- security or governance change +- repeated issue discovered +- useful pattern found diff --git a/docs/methodology/continuous-improvement-loop.md b/docs/methodology/continuous-improvement-loop.md new file mode 100644 index 0000000..ec4056d --- /dev/null +++ b/docs/methodology/continuous-improvement-loop.md @@ -0,0 +1,79 @@ +# Continuous Improvement Loop + +AI-OS must improve itself through an explicit loop. The agent does not silently mutate the project. It first creates a plan and asks for human approval when the scope is broad, risky, public, or structural. + +## Continuous improvement state machine + +```mermaid +stateDiagram-v2 + [*] --> Inspect + Inspect --> GapAnalysis + GapAnalysis --> ImprovementPlan + ImprovementPlan --> HumanApproval + HumanApproval --> Execute: approved + HumanApproval --> RevisePlan: needs changes + HumanApproval --> Stop: rejected + RevisePlan --> ImprovementPlan + Execute --> Verify + Verify --> UpdateDocs: passed + Verify --> Diagnose: failed + Diagnose --> Execute + UpdateDocs --> UpdateMemory + UpdateMemory --> Retrospective + Retrospective --> MoreValue + MoreValue --> GapAnalysis: valuable improvements remain + MoreValue --> Done: no meaningful improvement remains + Done --> [*] +``` + +## Rules + +1. Inspect the current repository state. +2. Fan out analysis to specialist roles. +3. Produce a prioritized plan. +4. Ask the human to approve the plan before broad changes. +5. Execute only the approved scope. +6. Verify with strong gates when possible. +7. Update docs, wiki navigation, roadmap, and memory. +8. Repeat until only optional low-value improvements remain. + +## Specialist fan-out + +```mermaid +flowchart LR + Goal[Improvement Goal] --> Orchestrator[Orchestrator] + Orchestrator --> Docs[Documentation Reviewer] + Orchestrator --> Security[Security Reviewer] + Orchestrator --> CI[CI/CD Reviewer] + Orchestrator --> UX[Reader Experience Reviewer] + Orchestrator --> Agent[Agent Prompt Reviewer] + Orchestrator --> Maintainer[Maintainer Reviewer] + Docs --> Synthesis[Synthesis] + Security --> Synthesis + CI --> Synthesis + UX --> Synthesis + Agent --> Synthesis + Maintainer --> Synthesis + Synthesis --> Plan[Approved Plan Candidate] +``` + +## Approval boundary + +Approval is required before: + +- changing governance +- changing release process +- changing security policy +- creating automation that writes to GitHub +- merging or releasing +- broad repository restructuring + +## Definition of complete + +The loop is complete when: + +- the original goal is satisfied +- the plan was followed or deviations were documented +- verifiers passed or exceptions are explicit +- docs and wiki are updated +- no high-value improvement remains in the current scope diff --git a/docs/methodology/definition-of-done.md b/docs/methodology/definition-of-done.md new file mode 100644 index 0000000..f2d35ec --- /dev/null +++ b/docs/methodology/definition-of-done.md @@ -0,0 +1,30 @@ +# Definition of Done + +A task is done only when every required gate is satisfied. + +## Required checks + +- Goal is achieved. +- Acceptance criteria are satisfied. +- Work is implemented in the intended scope. +- Relevant verification was run. +- Security and performance were considered. +- Documentation was updated when behavior changed. +- Wiki navigation was updated when public docs changed. +- Rollback or revert path is known. +- Remaining work is documented. + +## Done decision + +```mermaid +flowchart TD + Goal[Goal met?] --> A{Yes?} + A -- No --> Work[Continue loop] + A -- Yes --> Verify[Verifiers pass?] + Verify -- No --> Work + Verify -- Yes --> Docs[Docs updated?] + Docs -- No --> Work + Docs -- Yes --> Risk[Risk acceptable?] + Risk -- No --> Human[Human review] + Risk -- Yes --> Done[Done] +``` diff --git a/docs/methodology/state-machine-v2.md b/docs/methodology/state-machine-v2.md new file mode 100644 index 0000000..e511b57 --- /dev/null +++ b/docs/methodology/state-machine-v2.md @@ -0,0 +1,21 @@ +# AI-OS State Machine + +```mermaid +flowchart TD + A[Bootstrap] --> B[Understand] + B --> C[Discover] + C --> D[Analyze] + D --> E[Plan] + E --> F{Review needed?} + F -- Yes --> G[Human review] + F -- No --> H[Design] + G --> H + H --> I[Implement] + I --> J[Verify] + J --> K{Pass?} + K -- No --> D + K -- Yes --> L[Document] + L --> M[Done] +``` + +Every task moves through the same controlled process. The agent plans first, verifies before completion, and loops back when a check does not pass. diff --git a/docs/model-routing/local-first-policy.md b/docs/model-routing/local-first-policy.md new file mode 100644 index 0000000..7fb9062 --- /dev/null +++ b/docs/model-routing/local-first-policy.md @@ -0,0 +1,26 @@ +# Local-first Model Routing Policy + +AI-OS prefers local or cheaper models for low-risk work and escalates only when needed. + +## Routing loop + +```mermaid +flowchart TD + Task[Task] --> Risk{Risk level} + Risk -- Low --> Local[Local or small model] + Risk -- Medium --> Medium[Medium model] + Risk -- High --> Strong[Strong model] + Local --> Verify[Verifier] + Medium --> Verify + Strong --> Verify + Verify --> Confidence{Enough confidence?} + Confidence -- No --> Escalate[Escalate] + Escalate --> Verify + Confidence -- Yes --> Done[Done] +``` + +## Guidance + +- Use local models for summaries, search, boilerplate, and formatting. +- Use stronger models for architecture, security, hard debugging, and final review. +- Escalate only when confidence is low or risk is high. diff --git a/docs/model-routing/mcp.md b/docs/model-routing/mcp.md new file mode 100644 index 0000000..f8ece51 --- /dev/null +++ b/docs/model-routing/mcp.md @@ -0,0 +1,30 @@ +# MCP Integration Model + +Model Context Protocol fits AI-OS as the tool and context boundary. + +## AI-OS mapping + +| MCP concept | AI-OS role | +|---|---| +| Resources | repository context, docs, schemas, logs | +| Prompts | reusable loops and scenario prompts | +| Tools | controlled actions such as search, test, issue, PR, deploy | +| Human confirmation | approval gates before risky actions | + +## Tool-use gate + +```mermaid +flowchart TD + Need[Need external action] --> Tool[Select tool] + Tool --> Risk{Risky?} + Risk -- No --> Execute[Execute tool] + Risk -- Yes --> Explain[Explain action and risk] + Explain --> Human{Approved?} + Human -- No --> Alternative[Use safer path] + Human -- Yes --> Execute + Execute --> Verify[Verify result] +``` + +## Rule + +MCP tools should be visible, auditable, and bounded by approval gates. diff --git a/docs/security/ssdf-mapping.md b/docs/security/ssdf-mapping.md new file mode 100644 index 0000000..eb5275c --- /dev/null +++ b/docs/security/ssdf-mapping.md @@ -0,0 +1,29 @@ +# Secure SDLC Mapping + +AI-OS aligns with secure software development by making security part of every loop. + +## Security integration points + +```mermaid +flowchart TD + Plan[Plan] --> Threat[Threat review] + Threat --> Design[Secure design] + Design --> Implement[Implementation] + Implement --> Review[Security review] + Review --> Verify[Security verification] + Verify --> Docs[Document residual risk] +``` + +## AI-OS controls + +- human approval for security-sensitive changes +- tool-use visibility +- secret handling rules +- dependency review +- CI/CD safety checks +- release approval gates +- ADRs for security-impacting decisions + +## Output + +Every security-sensitive change should include threat, control, verifier, and residual risk. diff --git a/docs/security/supply-chain.md b/docs/security/supply-chain.md new file mode 100644 index 0000000..9f82a50 --- /dev/null +++ b/docs/security/supply-chain.md @@ -0,0 +1,26 @@ +# Supply Chain Security + +AI-OS treats workflows, dependencies, prompts, and tool access as part of the supply chain. + +## Supply chain loop + +```mermaid +flowchart TD + Change[Dependency or workflow change] --> Review[Review diff] + Review --> Scan[Scan] + Scan --> Risk[Risk classify] + Risk --> Approve{Approval needed?} + Approve -- Yes --> Human[Maintainer review] + Approve -- No --> Merge[Merge] + Human --> Merge + Merge --> Monitor[Monitor alerts] +``` + +## Controls + +- Dependabot configuration +- dependency review workflow +- secret scanning +- CodeQL for future scripts +- protected release workflow +- documented SBOM/provenance guidance diff --git a/docs/security/telemetry-and-privacy.md b/docs/security/telemetry-and-privacy.md new file mode 100644 index 0000000..1e72080 --- /dev/null +++ b/docs/security/telemetry-and-privacy.md @@ -0,0 +1,32 @@ +# Telemetry and Privacy + +AI-OS should be privacy-first. + +## Principles + +- No telemetry by default. +- Prefer local logs for local workflows. +- Do not collect secrets, prompts, private code, or personal data. +- Make any telemetry opt-in and documented. +- Keep observability useful for debugging loops and verifier outcomes. + +## Observability loop + +```mermaid +flowchart TD + Event[Loop event] --> Classify[Classify] + Classify --> Sensitive{Sensitive?} + Sensitive -- Yes --> Redact[Redact or drop] + Sensitive -- No --> Record[Record metric] + Redact --> Record + Record --> Review[Review usefulness] +``` + +## Useful metrics + +- loop count +- verifier pass rate +- time to recover +- docs drift +- release readiness +- model escalation count diff --git a/examples/continuous-improvement-task.md b/examples/continuous-improvement-task.md new file mode 100644 index 0000000..17daec8 --- /dev/null +++ b/examples/continuous-improvement-task.md @@ -0,0 +1,30 @@ +# Example: Continuous Improvement Task + +## Goal + +Improve AI-OS repository structure and documentation quality. + +## Loop + +Continuous improvement loop. + +## Plan + +1. Inspect repository. +2. Fan out review to docs, security, CI/CD, prompts, and wiki. +3. Create prioritized plan. +4. Ask human to approve plan. +5. Implement approved files. +6. Verify structure. +7. Open PR. + +## Verification + +- Required files exist. +- Docs contain Mermaid diagrams. +- Prompt library links to loops. +- Wiki pages point back to canonical docs. + +## Result + +A PR is opened rather than merged, preserving human control. diff --git a/prompts/bugfix.md b/prompts/bugfix.md new file mode 100644 index 0000000..a4cff7a --- /dev/null +++ b/prompts/bugfix.md @@ -0,0 +1,15 @@ +# Bug Fix Prompt + +```text +Execute AI-OS bug fix loop. + +Task: +[BUG] + +Reproduce when possible. +Create or describe a failing check. +Find the cause. +Make the smallest correction. +Run regression verification. +Update docs only if behavior or operations changed. +``` diff --git a/prompts/chatgpt-web.md b/prompts/chatgpt-web.md new file mode 100644 index 0000000..534bcfa --- /dev/null +++ b/prompts/chatgpt-web.md @@ -0,0 +1,36 @@ +# ChatGPT Web Operating Prompt + +Use this when working in ChatGPT web so the same loop-engineering method is used outside local coding agents. + +```text +Operate under AI Engineering Operating System. + +For this chat: +- Start by clarifying the goal when needed. +- Inspect available files, tools, and context before acting. +- Fan out internally into Planner, Architect, Implementer, Verifier, Security Reviewer, and Documentation Reviewer. +- Produce a short implementation plan before broad work. +- Ask for approval before public posts, repository mutations, releases, destructive changes, or high-risk actions. +- Execute approved work in small steps. +- Verify results using available tools. +- If verification fails, diagnose and loop back. +- Update docs, wiki, memory, and next-step plan when the task changes the project. +- End with evidence, remaining risks, and final status. +``` + +## ChatGPT loop + +```mermaid +flowchart TD + Goal[User goal] --> Context[Inspect context] + Context --> Plan[Plan] + Plan --> Approval{Approval needed?} + Approval -- Yes --> Human[Ask user] + Approval -- No --> Act[Act] + Human --> Act + Act --> Verify[Verify] + Verify --> Pass{Pass?} + Pass -- No --> Repair[Repair loop] + Repair --> Verify + Pass -- Yes --> Report[Report] +``` diff --git a/prompts/continuous-improvement.md b/prompts/continuous-improvement.md new file mode 100644 index 0000000..6f74d5b --- /dev/null +++ b/prompts/continuous-improvement.md @@ -0,0 +1,17 @@ +# Continuous Improvement Prompt + +```text +Execute AI-OS continuous improvement loop. + +Goal: +[IMPROVEMENT GOAL] + +Inspect the repository first. +Fan out analysis to documentation, governance, security, CI/CD, reader experience, and prompt specialists. +Create a prioritized plan. +Ask for human approval before implementation. +After approval, implement in small reversible steps. +Verify structure, links, diagrams, workflows, and documentation. +Update memory, roadmap, and wiki navigation. +Repeat until no high-value improvement remains in the approved scope. +``` diff --git a/prompts/feature.md b/prompts/feature.md new file mode 100644 index 0000000..7ef213e --- /dev/null +++ b/prompts/feature.md @@ -0,0 +1,16 @@ +# Feature Prompt + +```text +Execute AI-OS feature development loop. + +Task: +[FEATURE] + +Define user value and acceptance criteria first. +Inspect existing patterns. +Plan small reversible increments. +Ask for approval if the feature affects public behavior or architecture. +Implement incrementally. +Add or update tests and docs. +Verify before completion. +``` diff --git a/prompts/master-system-prompt.md b/prompts/master-system-prompt.md new file mode 100644 index 0000000..c6d7439 --- /dev/null +++ b/prompts/master-system-prompt.md @@ -0,0 +1,24 @@ +# Master System Prompt + +Use this prompt for local coding agents. + +```text +You are operating under AI Engineering Operating System. + +For every task: +1. Load repository context. +2. Identify the correct loop. +3. Fan out reasoning to specialist roles. +4. Produce a concise plan before implementation. +5. Ask for human approval before broad, risky, public, costly, or irreversible changes. +6. Execute only the approved scope. +7. Implement in small reversible steps. +8. Verify with the strongest available gates. +9. If a check does not pass, return to the earliest affected phase. +10. Update documentation, wiki navigation, memory, and changelog when needed. +11. Report evidence honestly. +12. Stop only when Definition of Done passes. + +Never claim a command was run if it was not run. +Never merge, release, deploy, or make destructive changes without approval. +``` diff --git a/scripts/verify_repo.py b/scripts/verify_repo.py new file mode 100644 index 0000000..7e23ae1 --- /dev/null +++ b/scripts/verify_repo.py @@ -0,0 +1,37 @@ +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + +REQUIRED = [ + 'README.md', + 'CONTRIBUTING.md', + 'CODE_OF_CONDUCT.md', + 'SECURITY.md', + 'GOVERNANCE.md', + 'VERSIONING.md', + 'CHANGELOG.md', + 'CODEOWNERS', + 'docs/methodology/continuous-improvement-loop.md', + 'docs/diagrams/README.md', + 'docs/loops/feature.md', + 'prompts/master-system-prompt.md', + 'prompts/chatgpt-web.md', + 'wiki/Home.md', +] + +missing = [p for p in REQUIRED if not (ROOT / p).exists()] +if missing: + print('Missing required files:') + for item in missing: + print(item) + raise SystemExit(1) + +markdown = list(ROOT.rglob('*.md')) +for path in markdown: + text = path.read_text(encoding='utf-8') + if not text.lstrip().startswith('#'): + print('Markdown file without title:', path.relative_to(ROOT)) + raise SystemExit(1) + +print('Repository structure OK') +print('Markdown files checked:', len(markdown)) diff --git a/tests/test_required_structure.py b/tests/test_required_structure.py new file mode 100644 index 0000000..e37ef60 --- /dev/null +++ b/tests/test_required_structure.py @@ -0,0 +1,23 @@ +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + + +def test_required_files_exist(): + required = [ + 'README.md', + 'CONTRIBUTING.md', + 'SECURITY.md', + 'GOVERNANCE.md', + 'VERSIONING.md', + 'docs/methodology/continuous-improvement-loop.md', + 'docs/loops/feature.md', + 'prompts/master-system-prompt.md', + ] + missing = [p for p in required if not (ROOT / p).exists()] + assert not missing + + +def test_markdown_files_have_titles(): + for path in ROOT.rglob('*.md'): + assert path.read_text(encoding='utf-8').lstrip().startswith('#'), path diff --git a/wiki/Architecture-Guide.md b/wiki/Architecture-Guide.md new file mode 100644 index 0000000..cd9fab2 --- /dev/null +++ b/wiki/Architecture-Guide.md @@ -0,0 +1,21 @@ +# Architecture Guide + +Canonical architecture docs are in docs/architecture. + +## Overview + +```mermaid +flowchart TD + A[Goal] --> B[Loop Router] + B --> C[Specialist Agents] + C --> D[Verification Gates] + D --> E{Done?} + E -- No --> B + E -- Yes --> F[Docs and Memory] +``` + +## Pages + +- docs/architecture/README.md +- docs/architecture/fan-out-fan-in.md +- docs/methodology/continuous-improvement-loop.md diff --git a/wiki/Home.md b/wiki/Home.md index b5a78ce..2210b90 100644 --- a/wiki/Home.md +++ b/wiki/Home.md @@ -2,35 +2,37 @@ Welcome to the AI-OS wiki. +The wiki is a curated browsing surface. The canonical source of truth remains in the repository docs. + ## Main pages - [Master Operating Manual](../docs/ai-os/master-operating-manual.md) +- [Continuous Improvement Loop](../docs/methodology/continuous-improvement-loop.md) - [Mermaid Diagram Catalog](../docs/diagrams/README.md) - [Loop Catalog](../docs/loops/README.md) +- [Verification Gates](../docs/verifiers/README.md) - [Prompt Templates](../prompts/README.md) +- [Architecture Guide](Architecture-Guide.md) +- [Loops](Loops.md) +- [Verifiers](Verifiers.md) +- [Prompts](Prompts.md) +- [Releases](Releases.md) ## What this is AI-OS is a repeatable operating framework for AI coding agents. -The core idea: - -```text -Prompt once. -Verify everything. -Loop until the goal is achieved. -Escalate when risk requires human approval. -``` - -## System overview - ```mermaid flowchart TD - Goal[Goal] --> Agent[AI Coding Agent] - Agent --> Context[Repository Context] - Agent --> Loop[Selected Engineering Loop] - Loop --> Verify[Verification Gates] + Goal[Goal] --> Context[Load context] + Context --> Specialists[Fan-out specialists] + Specialists --> Plan[Plan] + Plan --> Human{Approval needed?} + Human -- Yes --> Approval[Human approval] + Human -- No --> Work[Work] + Approval --> Work + Work --> Verify[Verify] Verify --> Done{Done?} - Done -- No --> Loop - Done -- Yes --> Report[Final Report] + Done -- No --> Work + Done -- Yes --> Report[Final report] ``` diff --git a/wiki/Loops.md b/wiki/Loops.md new file mode 100644 index 0000000..89f5088 --- /dev/null +++ b/wiki/Loops.md @@ -0,0 +1,25 @@ +# Loops + +Canonical loop docs are in docs/loops. + +## Loop map + +```mermaid +flowchart TD + Task[Task] --> Type{Type} + Type -- Feature --> Feature[Feature loop] + Type -- Bug --> Bug[Bug loop] + Type -- Pipeline --> Pipe[Pipeline loop] + Type -- Security --> Sec[Security loop] + Type -- Release --> Rel[Release loop] + Type -- Improvement --> Improve[Improvement loop] +``` + +## Pages + +- docs/loops/README.md +- docs/loops/feature.md +- docs/loops/bugfix-loop.md +- docs/loops/pipeline-repair.md +- docs/loops/security.md +- docs/loops/release.md diff --git a/wiki/Prompts.md b/wiki/Prompts.md new file mode 100644 index 0000000..6e5a7b4 --- /dev/null +++ b/wiki/Prompts.md @@ -0,0 +1,25 @@ +# Prompts + +Canonical prompt docs are in prompts. + +## Recommended prompts + +- prompts/master-system-prompt.md +- prompts/chatgpt-web.md +- prompts/feature.md +- prompts/bugfix.md +- prompts/continuous-improvement.md + +## Prompt loop + +```mermaid +flowchart TD + Prompt[Prompt] --> Context[Load context] + Context --> Loop[Select loop] + Loop --> Plan[Plan] + Plan --> Act[Act] + Act --> Verify[Verify] + Verify --> Done{Done?} + Done -- No --> Loop + Done -- Yes --> Report[Report] +``` diff --git a/wiki/Releases.md b/wiki/Releases.md new file mode 100644 index 0000000..ceb862b --- /dev/null +++ b/wiki/Releases.md @@ -0,0 +1,24 @@ +# Releases + +Canonical release docs are in VERSIONING.md and docs/ci-cd/release-process.md. + +## Release flow + +```mermaid +stateDiagram-v2 + [*] --> Freeze + Freeze --> Verify + Verify --> Approval + Approval --> Tag: approved + Approval --> Rework: rejected + Rework --> Verify + Tag --> Publish + Publish --> Validate + Validate --> [*] +``` + +## Pages + +- VERSIONING.md +- CHANGELOG.md +- docs/ci-cd/release-process.md diff --git a/wiki/Verifiers.md b/wiki/Verifiers.md new file mode 100644 index 0000000..eb88365 --- /dev/null +++ b/wiki/Verifiers.md @@ -0,0 +1,21 @@ +# Verifiers + +Canonical verifier docs are in docs/verifiers. + +## Gate flow + +```mermaid +flowchart TD + Change[Change] --> Build[Build] + Build --> Test[Test] + Test --> Docs[Docs] + Docs --> Risk[Risk review] + Risk --> Pass{Pass?} + Pass -- No --> Loop[Loop back] + Pass -- Yes --> Done[Done] +``` + +## Pages + +- docs/verifiers/README.md +- docs/methodology/definition-of-done.md