From eedcdd428236486d34c32d8081d4eac60d200082 Mon Sep 17 00:00:00 2001 From: CI Date: Fri, 29 May 2026 13:10:27 +0000 Subject: [PATCH] docs: rewrite README for v0.2.0 git-native architecture ---ci--- phase: 1 milestone: v0.2.0 status: complete ---/ci--- - Replace npm install with from-source instructions (package not published yet) - Add git-native architecture section with commit schema, branch strategy, reconstruction test - Add .ci/ file table explaining what lives where - Fix placeholder with actual Gitea URL - Add Current Limitations section (agent stubs, no npm publish, partial verif layers) - Update Differences from Learnship table for git-native era - Update Decision Engine section: audit trail is now git log - Update Agents table with orchestrator git-first modification --- README.md | 169 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 142 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 354d224..565dd9c 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,19 @@ # CI — Continuous Intelligence -Fully autonomous AI-driven software engineering harness. +Fully autonomous, git-native AI-driven software engineering harness. ## Overview CI (Continuous Intelligence) is an autonomous-first software engineering harness that eliminates human-in-the-loop overhead while preserving the rigor of guided development. It receives a specification, resolves ambiguities through a single Clarify phase, then executes the full pipeline — research, plan, execute, verify — autonomously. +**The git log IS the project memory.** Every decision, escalation, lesson learned, and verification result is encoded in commit messages using structured `---ci---` YAML blocks. An agent's first impulse to gather context is `git log`, not file reads. Another agent with access to only commit messages (no code, no diffs) can reconstruct the project state completely. + ## Installation -```bash -npm install -g @continuous-intelligence/ci -``` - -Or from source: +From source (package not yet published to npm): ```bash -git clone +git clone https://git.cloudinit.dev/continuous-intelligence/ci.git cd ci npm install npm run build @@ -31,9 +29,6 @@ ci init "Build a REST API for task management" # Initialize from a specification file ci init --spec ./specs/my-project.md -# Initialize with interactive clarify phase -ci init --clarify "Build a REST API for task management" - # Run the full autonomous pipeline ci run --all @@ -46,13 +41,10 @@ ci run verify # Execute an ad-hoc task ci quick "Add authentication middleware" -# Verify a phase -ci verify 1 - -# Check project status +# Check project status (reads from git log + branches) ci status -# Review autonomous decisions +# Review autonomous decisions (extracted from git log ---ci--- blocks) ci audit ci audit --verbose @@ -66,13 +58,113 @@ ci rollback 1 ci ship 1 ``` +## Git-Native Architecture (v0.2.0) + +### The Commit Schema + +Every CI-generated commit contains a `---ci---` YAML block with structured metadata: + +``` +feat(P01-01-02): create user registration endpoint + +---ci--- +phase: 1 +milestone: v1.0 +plan: 01-01 +task: 01-01-02 +status: execute +decisions: + - id: D-003 + decision: Use bcrypt with 12 rounds for password hashing + rationale: Industry standard; argon2 not available in target env + confidence: 0.88 + alternatives: [argon2, scrypt] +requirements: + covered: [AUTH-01] +---/ci--- + +- POST /auth/register validates email and password +- Checks for duplicate users +- Returns JWT token on success +``` + +### What Lives Where + +| Where | What | Why | +|-------|------|-----| +| `.ci/config.json` | Autonomy, thresholds, git strategy | Controls system behavior before any commits exist | +| `.ci/PROJECT.md` | Vision, core value, requirements, constraints, key decisions table | Long-lived strategic reference | +| `.ci/ARCHITECTURE.md` | System architecture, component boundaries, data flow | Long-lived technical reference | +| `.ci/ROADMAP.md` | Phase breakdown, milestone mapping, success criteria | Long-lived planning reference | +| `.ci/REQUIREMENTS.md` | v1/v2 requirements with REQ-IDs and traceability | Long-lived requirements reference | +| **Git commit bodies** | Decisions, escalations, lessons, compounds, verification results | Dynamic event stream — the audit trail | +| **Git branches** | Phase/milestone status | `phase/NN-slug` and `milestone/vX.X-slug` encode project structure | + +### Branch Strategy + +``` +main + └── milestone/v1.0-mvp + ├── phase/01-authentication # in progress if not merged + ├── phase/02-task-management + └── phase/03-realtime-notifications +``` + +- Branch exists + not merged = phase **in progress** +- Branch merged to milestone = phase **complete** +- Milestone branch merged to main = milestone **complete** + +### Context Reconstruction Protocol + +An agent starting a session gathers context in this order: + +1. `git log --oneline -20` — recent activity +2. `git branch -a` — phase/milestone structure +3. `git log -1 --format="%b"` — latest `---ci---` block +4. `.ci/config.json` — autonomy + thresholds +5. `.ci/PROJECT.md` — vision + constraints (when needed) +6. `.ci/ROADMAP.md` — phase plan + success criteria (when needed) +7. `.ci/REQUIREMENTS.md` — REQ-IDs + traceability (when planning) +8. `.ci/ARCHITECTURE.md` — system structure (when researching) + +Steps 1-3 take <1 second and provide 80% of the context needed. + +### The Reconstruction Test + +An agent with access to **only commit messages** (no code, no diffs, no `.ci/` files) can reconstruct: + +| Reconstructable | How | +|---------------|-----| +| Project specification | Init commit body | +| Current phase | `---ci---.phase` field + branch status | +| Current milestone | Branch names + `---ci---.milestone` field | +| All decisions with rationale | `git log --grep="decisions:" --format="%b"` | +| Decision confidence | Each decision has `confidence: 0.XX` | +| Alternatives considered | Each decision has `alternatives: [...]` | +| Requirements coverage | `git log --grep="requirements:" --format="%b"` | +| Lessons learned | `git log --grep="lessons:" --format="%b"` | +| Compounded solutions | `git log --grep="compound:" --format="%b"` | +| Escalation history | `git log --grep="escalation:" --format="%b"` | + +### Commit Types + +In addition to conventional commit types, CI uses: + +| Type | When Used | +|------|-----------| +| `decision` | Autonomous decision logged (no code change) | +| `compound` | Compounded solution captured | +| `escalation` | Escalation raised or resolved | +| `verify` | Verification pass/fail | +| `wip` | Work-in-progress checkpoint | + ## Autonomy Levels | Level | Behavior | |-------|----------| | `full` | No human interaction after Clarify. Escalate only irreversible decisions. | | `supervised` | Escalate on every Escalation Gate plus verification failures. | -| `guided` | Escalate on every Decision Gate. Closest to Learnship behavior. | +| `guided` | Escalate on every Decision Gate. | ## Configuration @@ -120,24 +212,34 @@ CI uses `.ci/config.json` for project configuration: ``` SPECIFY → CLARIFY → RESEARCH → PLAN → EXECUTE → VERIFY → COMPLETE - ↕ ↕ ↕ ↕ - (questions) (auto-decide) (auto-run) (auto-verify) + ↕ ↕ ↕ ↕ + (questions) (auto-decide) (auto-run) (auto-verify) ``` +### Git-Native Core Modules + +| Module | Purpose | +|--------|---------| +| `commit-parser` | `---ci---` YAML block extraction and parsing from commit messages | +| `commit-builder` | Structured commit message generation for all commit types | +| `git-context` | Project state reconstruction from `git log` + `git branch` | +| `git-branch` | Phase/milestone branch lifecycle management | +| `ci-files` | `.ci/` long-lived reference file management with update discipline | + ### Decision Engine Every autonomous decision is classified by confidence: -- **High (>0.85)**: Auto-decide, log to audit trail +- **High (>0.85)**: Auto-decide, commit as `---ci---` block - **Medium (0.60-0.85)**: Auto-decide with assumption logging, flag for review - **Low (<0.60)**: Escalate to human +Decisions are committed to git as `decision` type commits. The audit trail is `git log --grep="decisions:"`. + ### 18 Agents -All 17 Learnship agents retained, plus the CI Orchestrator: - -| Agent | Role | Modification | -|-------|------|-------------| -| orchestrator | Pipeline controller | New — replaces interactive workflows | +| Agent | Role | CI Modification | +|-------|------|----------------| +| orchestrator | Pipeline controller | Git-first context loading, `---ci---` commit generation | | planner | Plan creation | Never sets `autonomous: false` | | executor | Task execution | Never pauses for checkpoints | | verifier | Output verification | Generates automated tests, not human UAT | @@ -145,7 +247,7 @@ All 17 Learnship agents retained, plus the CI Orchestrator: | challenger | Plan stress-testing | Binding verdicts, only escalates <0.60 | | security-auditor | Security audit | Auto-dispositions threats | | debugger | Bug fixing | Auto-fixes when confidence > threshold | -| Others | Various | Unchanged from Learnship | +| Others | Various | Retained from Learnship | ### Verification Layers @@ -186,17 +288,30 @@ When CI cannot proceed autonomously: 4. **Security Escalation**: High-severity threat detected 5. **Specification Ambiguity**: Multiple valid interpretations -Each escalation includes a recommended default with auto-proceed timeout. +Each escalation is committed as an `escalation` type commit. Resolved escalations produce a follow-up commit with the resolution. The full escalation history is available via `git log --grep="escalation:"`. + +## Current Limitations + +- **Agent implementations are stubs**: All 18 agents return success immediately. Real LLM-based agent implementations are needed for research, planning, execution, and verification. +- **Package not published to npm**: Install from source only until a publishing pipeline is configured. +- **Behavioral/Security/Quality verification layers**: Structural verification is fully implemented; behavioral, security, and quality layers are partially stubbed. ## Differences from Learnship | Dimension | Learnship | CI | |-----------|-----------|-----| +| Project memory | `.planning/` directory files | Git log + `---ci---` commit blocks | +| Audit trail | `.ci/audit/*.json` files | `git log --grep="decisions:"` | +| State management | `STATE.md` + `STATE.md.json` | Reconstructed from git on demand | +| Phase discovery | Read `.planning/phases/` directory | `git branch -a \| grep phase/` | | Human Interactions | 19+/lifecycle | 1-2/lifecycle | | Decision Making | Human decides, agent implements | Agent decides, human reviews post-hoc | | Verification | Human UAT | Automated tests + escalation | | Specification | Multi-round conversation | Single spec file | -| Learning Curve | Moderate | Low (5 core commands) | + +## Repository + +[git.cloudinit.dev/continuous-intelligence/ci](https://git.cloudinit.dev/continuous-intelligence/ci) ## License