Jon Chery
8c975352b8
---ci---
phase: 1-5
milestone: v0.11
project: ci
status: execute
decisions:
- id: D-092
decision: Independent sessions via AgentSession (not shared state)
rationale: Aligns with git-native model; sessions communicate through commits and .ciagent/ files
confidence: 0.90
- id: D-093
decision: Personas as runtime configs (not new Agent classes)
rationale: Less code, more flexible. Persona md files define domain knowledge and framework opinions.
confidence: 0.88
- id: D-094
decision: Lead developer as task decomposer (not separate pipeline stage)
rationale: EXECUTE stays one stage. Lead decomposes before execution, each persona group runs.
confidence: 0.85
- id: D-095
decision: File-based git locking (not DB or IPC)
rationale: Git-native. .session-lock files are simple JSON with session ID, timestamp, project slug.
confidence: 0.87
- id: D-096
decision: Territory enforcement with warn/strict modes
rationale: Warn for teams learning boundaries. Strict for mature projects. Configurable per-project.
confidence: 0.82
- id: D-097
decision: Task decomposition by file patterns + requirement IDs
rationale: File patterns are deterministic; no LLM needed. Requirement IDs in PLAN.md already map to domains.
confidence: 0.88
requirements:
covered: [SESSION-01, SESSION-02, SESSION-03, SESSION-04, SESSION-05, PERSONA-01, PERSONA-02, PERSONA-03, PERSONA-04, PERSONA-05, PERSONA-06, PERSONA-07, PERSONA-08, PERSONA-09, PERSONA-10, PERSONA-11, CLI-01, CLI-02, CLI-03, CLI-04, INTEG-01, INTEG-02, INTEG-03, INTEG-04, INTEG-05]
---/ci---
218 lines
16 KiB
Markdown
218 lines
16 KiB
Markdown
# AGENTS.md — CIAgent 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
|
||
|
||
CIAgent (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/ # 19 agent implementations (persona loaders delegating to backends)
|
||
backends/ # Intelligence backend layer
|
||
types.ts # IntelligenceBackend, BackendRequest, BackendResult, BackendConfigSection
|
||
tool-registry.ts # CIAgent-owned tool implementations (readFile, writeFile, editFile, runBash, glob, grep)
|
||
llm-base.ts # Abstract base for LLM backends (shared tool loop, prompt construction)
|
||
ollama-local.ts # OllamaLocalBackend (localhost:11434)
|
||
ollama-cloud.ts # OllamaCloudBackend (remote endpoint, auth, rate limiting)
|
||
openai.ts # OpenAIBackend (OpenAI API, gpt-4o)
|
||
anthropic.ts # AnthropicBackend (Anthropic API, Claude)
|
||
opencode.ts # OpencodeBackend (shells out to opencode --non-interactive)
|
||
index.ts # Backend registry + auto-detection
|
||
cli/ # Commander.js CLI (commands.ts, index.ts)
|
||
core/ # Core engine components
|
||
artifacts.ts # Legacy .ciagent/ artifact management (retained for backward compat)
|
||
audit.ts # Git-native audit trail — reads decisions/escalations from git log
|
||
agent-session.ts # Multi-session support: AgentSession, file-based git locking
|
||
session-manager.ts # SessionManager: concurrent session lifecycle management
|
||
ciagent-files.ts # .ciagent/ 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 # .ciagent/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
|
||
persona-loader.ts # Execute-time persona resolution from .config/opencode/agents/*.md
|
||
task-decomposer.ts # Plan decomposition into data/backend/frontend task groups
|
||
types/ # Type definitions
|
||
commit-meta.ts # CIAgentMetadata, CommitDecision, CommitEscalation, ParsedCIAgentCommit (includes session field)
|
||
config.ts # CIAgentConfig, AutonomyLevel, ModelProfile, SessionConfig, PersonaConfigSection, DEFAULT_CIAGENT_CONFIG (includes backend)
|
||
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
|
||
persona.ts # ExecutePersonaConfig, PersonaDomain, TerritoryConflict, DecomposedPlan, DEFAULT_PERSONAS
|
||
session.ts # SessionInfo, SessionStatus, SessionConfig, DEFAULT_SESSION_CONFIG
|
||
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 infrastructure checks (static analysis, no test generation yet)
|
||
security.ts # Layer 3: regex-based threat pattern scanning (no STRIDE analysis yet)
|
||
quality.ts # Layer 4: regex-based code quality checks (no multi-persona review yet)
|
||
index.ts # Public API exports
|
||
version.ts # VERSION = "0.9.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
|
||
- **19 agents** purpose-built for CIAgent, all configured for autonomous operation. OrchestratorAgent is CIAgent-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. `.ciagent/` holds only long-lived reference docs (PROJECT.md, ARCHITECTURE.md, ROADMAP.md, REQUIREMENTS.md, config.json).
|
||
- **Artifact compatibility**: CIAgent no longer writes `.planning/` schema. `.ciagent/` files follow a CIAgent-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` (AgentName), `description`, `workflow`, and `execute(context: AgentContext): Promise<AgentResult>`. Agents delegate to `context.backend` when available, fail honestly when not.
|
||
- **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**: `CIAgentConfig` type and `DEFAULT_CIAGENT_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 → IDEATE → PLAN → EXECUTE → TEST → VERIFY → COMPLETE
|
||
```
|
||
|
||
Each stage is executed by `OrchestratorAgent.executeStage()`. The orchestrator delegates intelligent stages (research, plan, execute, test, verify) to specialized agents via `context.backend` when available, falling back to mechanical execution when no backend is configured. Mechanical stages (specify, clarify, complete) are always handled by the orchestrator directly.
|
||
|
||
## Intelligence Backend Architecture
|
||
|
||
```
|
||
IntelligenceBackend (unified interface)
|
||
├── LLMBackend (CIAgent runs tool loop, provides tools, constructs prompts)
|
||
│ ├── OllamaLocalBackend (localhost:11434, no auth)
|
||
│ ├── OllamaCloudBackend (remote endpoint, API key, rate limits)
|
||
│ ├── OpenAIBackend (OpenAI API, gpt-4o, API key auth)
|
||
│ └── AnthropicBackend (Anthropic API, Claude, API key auth)
|
||
└── AgentBackend (agent runs own tool loop, CIAgent sends request)
|
||
├── OpencodeBackend (opencode --non-interactive)
|
||
└── (future: Codex, Claude Code, Hermes, etc.)
|
||
```
|
||
|
||
- **LLM backends**: CIAgent constructs system prompts from persona.md + workflow.md, defines tool schemas, runs the tool-call loop via `ToolRegistry`, and parses structured JSON output
|
||
- **Agent backends**: CIAgent serializes `BackendRequest`, invokes the agent, and parses JSON `BackendResult` from stdout
|
||
- **Auto-detection** (provider: "auto"): tries opencode → openai → ollama-local → ollama-cloud → anthropic → fails with instructions
|
||
- **Per-command override**: `ciagent run --backend ollama-local` forces a specific backend (options: opencode, openai, anthropic, ollama-local, ollama-cloud)
|
||
- **Config**: `backend` section in `.ciagent/config.json` with provider, fallback, agent_backends, llm_backends
|
||
|
||
## 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**: Test execution and requirement traceability — runs test framework, parses results, reports pass/fail per suite
|
||
3. **Security**: Full STRIDE threat pattern scanning with CWE mapping and confidence-based auto-disposition
|
||
4. **Code Quality**: 3-persona code review (security, performance, maintainability) with P0/P1/P2 findings
|
||
|
||
## Testing
|
||
|
||
- Test framework: Jest with ts-jest
|
||
- Test file pattern: `**/*.test.ts` in `src/`
|
||
- Run: `npm run test`
|
||
- 58 test suites, 561 tests covering types, core, git-native, verification, agent, backends, ideation, multi-project, 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
|
||
|
||
- `.ciagent/config.json` — Project-level CIAgent configuration (autonomy, parallelization, verification, security, git)
|
||
- `.ciagent/PROJECT.md` — Vision, core value, requirements, constraints, key decisions table
|
||
- `.ciagent/ARCHITECTURE.md` — System architecture, component boundaries, data flow
|
||
- `.ciagent/ROADMAP.md` — Phase breakdown, milestone mapping, success criteria, progress table
|
||
- `.ciagent/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.10.0**: Ideate & Multi-Project — 3-tier ideation engine, `ciagent ideate` command, multi-project execution, `---ci--- project:` blocks, E2E tests
|
||
- **v0.9.0**: Integration & hardening — OpenAI and Anthropic backends, all 19 agents with intrinsic mechanical logic, E2E v0.9 integration tests, parallel agent execution
|
||
- **v0.8.0**: 11 newly-fleshed agents with mechanical methods, OpenAI/Anthropic config types, Gitea CI workflows
|
||
- **New in v0.11**: Multi-session support with `SessionManager` and `AgentSession` for independent project pipelines running concurrently, execute-phase persona specialization (`lead-developer`, `data-engineer`, `backend-engineer`, `frontend-engineer`) with territory enforcement and task decomposition, `ciagent sessions` CLI command with list/status/cancel/cleanup subcommands, `--session <id>` flag on `ciagent run`, `---ci--- session:` commit metadata field, `sessions` and `personas` config sections
|
||
- **v0.10.0**: Ideate & Multi-Project — 3-tier ideation engine, `ciagent ideate` command, multi-project execution, `---ci--- project:` blocks, E2E tests
|
||
- **New backends (v0.9)**: OpenAIBackend (gpt-4o, API key auth, OpenAI-Organization header), AnthropicBackend (Claude, API key auth, anthropic-version header, tool use translation)
|
||
- **Config expansion (v0.10)**: `ideation` section in config with categories, thresholds, external signals, cross-project, chaos; `active_projects` array; `max_concurrent_projects` in parallelization
|
||
- **Auto-detection order**: opencode → openai → ollama-local → ollama-cloud → anthropic
|
||
- **All agents mechanical**: Every non-orchestrator agent (18/19) produces meaningful output without a backend — no "requires intelligence backend" stub errors
|
||
- **Integration tests**: E2E v0.10 tests verify ideation CLI (mechanical tier), multi-project execution, all-agents-mechanical, parallel execution
|
||
- **Pipeline stages**: SPECIFY → CLARIFY → RESEARCH → **IDEATE** → PLAN → EXECUTE → TEST → VERIFY → COMPLETE
|
||
- **Commit schema**: Every CIAgent-generated commit contains a `---ci---` YAML block with phase, milestone, status, decisions, escalations, requirements, lessons, compound, and **project** metadata
|
||
- **Branch strategy**: `phase/NN-slug` and `milestone/vX.X-slug` branches encode project structure; merged = complete, active = in progress
|
||
- **CLI commands**: `init`, `run`, `quick`, `debug`, `verify`, `review`, `status`, `audit`, `clarify`, `rollback`, `ship`, `ideate`, `projects`
|
||
- **Intelligence backends**: 5 options — OpenAI (LLM), Anthropic (LLM), OllamaLocal (LLM, localhost), OllamaCloud (LLM, remote), Opencode (Agent, --non-interactive). Auto-detection: opencode → openai → ollama-local → ollama-cloud → anthropic.
|
||
- **Tests**: 58 test suites, 561 tests covering types, config, decision-engine, escalation, clarify, commit-parser, commit-builder, git-context, git-branch, ciagent-files, ideation, multi-project, all 4 verification layers, file utils, backends (ollama, openai, anthropic, opencode, tool-registry), agents (all 18 non-orchestrator), zod validation, E2E, parallel execution |