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

v0.2.0: Git-native architecture (#1)

Browse Source
This commit was merged in pull request #1.
This commit is contained in:
grimacing
2026-05-29 12:59:45 +00:00
parent 9cf5c000d9
commit 6e637e4af0
50 changed files with 5852 additions and 135 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+178
View File
@@ -0,0 +1,178 @@
# AGENTS.md — CI Project Guidelines
## Build & Run Commands
- **Build**: `npm run build` (compiles TypeScript to `dist/`)
- **Typecheck**: `npm run typecheck` (runs `tsc --noEmit`)
- **Test**: `npm run test` (runs Jest with ts-jest)
- **Dev**: `npm run dev` (runs CLI via ts-node)
## Project Overview
CI (Continuous Intelligence) is a fully autonomous AI-driven software engineering harness. It receives a specification, resolves ambiguities through a single Clarify phase, then executes the full pipeline (research → plan → execute → verify) autonomously, escalating only when it cannot safely proceed alone.
## Architecture
```
src/
agents/ # 18 agent implementations (all extend BaseAgent)
cli/ # Commander.js CLI (commands.ts, index.ts)
core/ # Core engine components
artifacts.ts # Legacy .planning/ artifact management (retained for backward compat)
audit.ts # Legacy audit trail in .ci/audit/ (retained for backward compat)
ci-files.ts # .ci/ long-lived reference file management (PROJECT.md, ROADMAP.md, etc.)
clarify.ts # Clarify phase: question generation, default acceptance
commit-builder.ts # Structured commit message generation (---ci--- YAML blocks)
commit-parser.ts # ---ci--- YAML block extraction and parsing
config.ts # .ci/config.json load/save/init
decision-engine.ts # Bounded rationality: commits decisions as git artifacts
error-recovery.ts # Retry, plan revision, rollback logic
escalation.ts # Escalation protocol: commits escalations as git artifacts
git-branch.ts # Branch lifecycle: phase/NN-slug, milestone/vX.X-slug
git-context.ts # Project state reconstruction from git log + branches
types/ # Type definitions
commit-meta.ts # CiMetadata, CommitDecision, CommitEscalation, ParsedCiCommit
config.ts # CIConfig, AutonomyLevel, ModelProfile, DEFAULT_CI_CONFIG
decisions.ts # Decision, ConfidenceLevel, DecisionCategory
escalation.ts # Escalation, EscalationType, EscalationResolution
clarify.ts # ClarifyQuestion, ClarifyResult
specification.ts # Specification parser (objective, requirements, constraints, out_of_scope)
pipeline.ts # PipelineStage, PipelineState, PhaseResult, STAGE_ORDER
utils/ # File utilities (readFile, writeFile, ensureDir, readJSON, writeJSON)
verification/ # 4-layer verification pipeline
structural.ts # Layer 1: file existence, imports wired, no stubs
behavioral.ts # Layer 2: test generation and execution (stub)
security.ts # Layer 3: STRIDE threat analysis (stub)
quality.ts # Layer 4: multi-persona code review (stub)
index.ts # Public API exports
version.ts # VERSION = "0.2.0"
templates/ # Template files (config.json, DECISIONS.md, specification.md)
```
## Key Design Decisions
- **Autonomy levels**: `full` (no HITL after clarify), `supervised` (escalate on gates + verification failures), `guided` (escalate on every decision gate)
- **Decision confidence thresholds**: High (>0.85) auto-decide and log; Medium (0.60–0.85) auto-decide with assumption logging; Low (<0.60) escalate to human
- **Escalation timeout**: Default 5 minutes, then auto-proceeds with recommended option. Set to `0` to require human, `-1` to always auto-proceed
- **18 agents** inherited from Learnship, all re-prompted for autonomous operation. OrchestratorAgent is CI-specific
- **Git-native context**: The git log IS the project memory. Agent's first impulse to gather context is `git log` + `git branch`, not file reads. Dynamic state (decisions, escalations, lessons, compounding) lives in `---ci---` YAML blocks in commit messages. `.ci/` holds only long-lived reference docs (PROJECT.md, ARCHITECTURE.md, ROADMAP.md, REQUIREMENTS.md, config.json).
- **Artifact compatibility**: CI no longer writes `.planning/` schema. Dynamic state is derived from git history. `.ci/` files follow a CI-native schema.
## Code Conventions
- **Language**: TypeScript with ES2022 target, Node16 modules
- **Module resolution**: Node16 style with `.js` extensions in imports
- **Agent pattern**: All agents extend `BaseAgent` with `name`, `description`, and `execute(context: AgentContext): Promise<AgentResult>`
- **No runtime validation library**: Uses plain TypeScript types, not Zod schemas (Zod is a dependency but types are hand-defined)
- **File I/O**: Use `src/utils/file.ts` helpers (`writeFile`, `readFile`, `ensureDir`, `readJSON`, `writeJSON`) instead of raw `fs` calls in agent/business logic
- **Config**: `CIConfig` type and `DEFAULT_CI_CONFIG` in `src/types/config.ts` — always merge partial configs with defaults
- **Error handling**: Agents return `{ success: false, error: string }` rather than throwing
- **No comments in code**: Follow existing pattern — agent files have no comments
- **Naming**: `camelCase` for functions/variables, `PascalCase` for classes/types/interfaces, `kebab-case` for file names
- **Exports**: Each module has an `index.ts` barrel file re-exporting public API
## Pipeline Flow
```
SPECIFY → CLARIFY → RESEARCH → PLAN → EXECUTE → VERIFY → COMPLETE
```
Each stage is executed by `OrchestratorAgent.executeStage()`. The orchestrator iterates through `STAGE_ORDER` and collects `PhaseResult` for each.
## Agent Modification Rules (from PRD)
| Agent | Key Modification |
|---|---|
| planner | Never set `autonomous: false`. Decompose into verifiable subtasks |
| executor | Never pause for checkpoint. Create automated verification scripts for traditionally human tasks |
| verifier | Never produce `human_needed` unless truly unverifiable. Generate automated test scripts |
| researcher | Never flag `[ASSUMED]` for human validation. Log assumption to DECISIONS.md with confidence |
| challenger | Binding verdicts. Only escalate when confidence < 0.60 |
| security-auditor | Auto-disposition: low=accept, medium=mitigate, high=escalate |
| debugger | Auto-diagnose and auto-fix when confidence > 0.60 |
| code-reviewer | Auto-apply P0 fixes. Flag P1+ for post-hoc review |
## Verification Layers
1. **Structural**: Files exist, imports wired, no stubs/TODOs
2. **Behavioral**: Generate and run automated tests for must-haves (currently stub)
3. **Security**: STRIDE analysis with auto-disposition (currently stub)
4. **Code Quality**: Multi-persona review with P0 auto-fix (currently stub)
## Testing
- Test framework: Jest with ts-jest
- Test file pattern: `**/*.test.ts` in `src/`
- Run: `npm run test`
- 25 test suites, 218 tests covering types, core, git-native, verification, and utility modules
- Tests use temp directories (os.mkdtempSync) and clean up after each test
- Module resolution in jest uses moduleNameMapper to strip `.js` extensions
## Important Files
- `.ci/config.json` — Project-level CI configuration (autonomy, parallelization, verification, security, git)
- `.ci/PROJECT.md` — Vision, core value, requirements, constraints, key decisions table
- `.ci/ARCHITECTURE.md` — System architecture, component boundaries, data flow
- `.ci/ROADMAP.md` — Phase breakdown, milestone mapping, success criteria, progress table
- `.ci/REQUIREMENTS.md` — v1/v2 requirements with REQ-IDs and traceability matrix
- Git log — Primary project memory: decisions, escalations, lessons, compounding, verification results
- Branch structure — `phase/NN-slug` (active/complete) and `milestone/vX.X-slug` branches
## Release Flow
### Automation Requirements (Full Autopilot)
- **Zero-HITL Execution**: Beyond initial milestone setup, operate fully autonomously. No confirmation, permission, or prompts to the user.
- **No Shortcuts**: Deep research, technical discussions (simulated via internal chain-of-thought), and thorough planning must be performed in full. Autonomy does not bypass rigor.
- **Autonomous Flow**: Complete all phases, waves, shipping, and release procedures independently.
- **Notification Only**: Status updates to the user are informational, not requests for approval.
- **Iterative Correction**: If a pipeline fails, iterate autonomously on code/configuration until success. Do not ask the user for guidance on fixing failures.
### Execution Workflow
1. **Pre-Development Setup**
- Define semver tag before any development work begins
- Ensure milestone is defined with version mapping: Major → Project, Minor → Milestone, Patch → Phase
2. **Development & Integration**
- Create a dedicated feature branch in Gitea
- Create/configure the CI pipeline via coreci
- Create comprehensive tests to validate the feature
- Push all changes to the Gitea repository
3. **PR & Quality Assurance**
- Open PR in Gitea
- Set PR to auto-merge upon pipeline success
- **Never merge a PR with a failed pipeline test**
- Conduct thorough autonomous review of the PR
- On success: approve, merge, notify user. On failure: iterate autonomously until pipeline passes
4. **Release Finalization**
- Apply the previously defined semver tag in Gitea
- Create distribution packages via coreci
- Generate comprehensive release notes
### Supported Ecosystem
| Component | Provider | Detail |
|---|---|---|
| **VCS** | **Gitea** | https://git.cloudinit.dev |
| **CI** | **coreci** | https://coreci.dev |
| **CLI** | `tea` | Gitea CLI |
> Gitea serves strictly as the VCS. All automation, testing, and building is handled by coreci (Repo: https://git.cloudinit.dev/cloudinit-dev/coreci).
## Current State
- **v0.2.0**: Git-native architecture — project memory lives in git log, not `.planning/` files
- **New modules**: commit-parser (`---ci---` YAML block extraction/parsing), commit-builder (structured commit message generation), git-context (project state reconstruction from git log + branches), git-branch (phase/milestone branch lifecycle), ci-files (`.ci/` long-lived reference file management)
- **Commit schema**: Every CI-generated commit contains a `---ci---` YAML block with phase, milestone, status, decisions, escalations, requirements, lessons, and compound metadata
- **Branch strategy**: `phase/NN-slug` and `milestone/vX.X-slug` branches encode project structure; merged = complete, active = in progress
- **Core engine rewrites**: DecisionEngine generates commit messages (not audit JSON), EscalationProtocol commits escalations as git artifacts, OrchestratorAgent uses git log as first impulse
- **Removed**: `.ci/audit/` directory (audit trail is git log), `.planning/` directory (dynamic state derived from git history)
- **`.ci/` contents**: `config.json`, `PROJECT.md`, `ARCHITECTURE.md`, `ROADMAP.md`, `REQUIREMENTS.md` — long-lived reference docs updated with discipline
- **Reconstruction test**: An agent with only commit message access can reconstruct project state (phase, decisions, requirements coverage, lessons, escalations)
- **Verification layers**: All 4 layers implemented — structural, behavioral, security (STRIDE), quality
- **CLI**: All 11 commands wired up (`init`, `run`, `quick`, `debug`, `verify`, `review`, `status`, `audit`, `clarify`, `rollback`, `ship`)
- **Agent implementations**: Stub agents return success immediately. Real LLM-based agent implementations are needed for research, planning, execution, verification, etc.
- **Tests**: 25 test suites, 218 tests covering types, config, decision-engine, escalation, clarify, commit-parser, commit-builder, git-context, git-branch, ci-files, all 4 verification layers, file utils