178 lines
11 KiB
Markdown
178 lines
11 KiB
Markdown
# 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 |