continuous-intelligence/ci
2
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases 29 Wiki Activity

docs: rewrite README for v0.2.0 git-native architecture

Browse Source 
---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 <repo-url> 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
This commit is contained in:
CI
2026-05-29 13:10:27 +00:00
parent 6e637e4af0
commit eedcdd4282
1 changed files with 142 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+142 -27
View File
@@ -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 <repo-url>
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