CLike β Governed AI-Native Delivery for Coding Agents
![]()
From intent to impact. CLike turns an idea into reviewed, tested and promotable software through a governed lifecycle in which cloud models and local coding agents execute, while deterministic evaluation and gates decide.
Abstract
Coding agents (Claude Code, Codex CLI, cloud LLMs) can now produce large amounts of code quickly. The open problem is no longer generation but governance: keeping intent, requirements, implementation, tests and promotion decisions aligned, auditable and safe when much of the work is performed by autonomous agents.
CLike is an R&D platform that addresses this problem with three ideas:
- A structured lifecycle (Harper) β
IDEA β SPEC β PLAN β KIT β EVAL β GATE β FINALIZEβ where every phase produces canonical, reviewable artifacts and each requirement (REQ) advances through short, verifiable loops. - Agent-agnostic execution under one contract β the same phase contract (inputs, expected outputs, allowed write roots, validation) is rendered either as a cloud prompt or as an execution package for a local agent, so the choice of executor never bypasses governance.
- Evidence-based promotion β a deterministic eval runner produces evidence, and the gate, not a model, decides whether a candidate can be promoted.
The developer leads. CLike governs.
Models and agents execute. Eval and Gate decide.
Highlights
- From idea to running solution β
IDEA β SPEC β PLAN β (KIT β EVAL β GATE)* β FINALIZE: every REQ is implemented, verified in a sandbox and promoted only through a gate;/finalizedelivers the solution configured and started, with a report of everything it did. - Release after release β
/idea --extendevolves a delivered project: new needs indocs/inputs/vN/merged into IDEA and SPEC, new REQs typed ADDED / MODIFIED / REMOVED, delivered REQs protected by the regression. - Any executor, same rules β cloud models, Claude Code and Codex receive the same context and the same contracts; BMAD roles can guide each phase.
- Governance that cannot be bypassed β locked acceptance tests, regression of delivered REQs,
evidence-based gate, 3-way promotion, audit; repairs from the real failures (
/eval --fix). - Drivable by agents β through MCP, Claude Code and Codex can run a whole project from
/initto/finalize, while CLike still governs every step. - Local and stack-agnostic β Podman or Docker, any language and infrastructure.
CLike at a glance β β the picture of the whole, area by area.
Estimating with CLike β β a worked enterprise estimate (five services on an event broker): classic work breakdown and staffing against the same scenario with CLike, on measured pilots β about 7β9Γ on effort and 8β12Γ on calendar, up to 10Γ on building and verifying well-specified requirements.
The chat (UI) β β what you see in VS Code: the chat, the cockpit (project, next action, REQs, methodology, last run), the run card and Stop.
Status
| Version | Date | Milestone |
|---|---|---|
| 1.9.10 | 2026-11 | An already broken test stays already broken: the same failing tests with other values in their messages are not a new error of the candidate. See CHANGELOG. |
| 1.9.11 | 2026-11 | The failed tests read from the whole output: an already failing test with other values in its message is recognised in a real report. See CHANGELOG. |
| 1.10.0 | 2026-11 | Where the time and the money go: the telemetry portal drills a phase down to its requirements, ranks the requirements by cost, time, repairs and failed evals, and gives KPIs and an estimate for the next ones. See CHANGELOG. |
| 1.10.1 | 2026-11 | The eval after a good KIT: /plan keeps what the release declared (amended REQs, superseded checks, regression environment), a regression whose environment did not come up runs once more, a sandbox database slow under load is retried, a check run alone gets its setup, and an interrupted eval runs again. See CHANGELOG. |
| 1.10.2 | 2026-11 | A promoted REQ reaches the default branch: the gate merge is retried when another git process holds the index for a moment, and /autopilot stops instead of building again a REQ promoted on a branch it is not on. See CHANGELOG. |
The last five versions; every version and change is in the CHANGELOG.
CLike is research software under active development. Interfaces may change between minor versions.
Core concepts
Harper lifecycle
| Phase | Purpose | Canonical output |
|---|---|---|
/idea |
Formalize the idea, scope and constraints | docs/harper/IDEA.md |
/spec |
Business and technical requirements | docs/harper/SPEC.md |
/plan |
Requirements (REQ) with acceptance criteria, lanes and dependencies | docs/harper/PLAN.md, plan.json |
/kit <REQ> |
Implement one REQ as a candidate: code, tests, docs, CI profile | runs/kit/<REQ>/β¦ |
/eval <REQ> |
Run the REQβs checks and collect evidence | eval report |
/gate <REQ> |
Decide promotability from the evidence | gate report |
/idea --extend |
Next release of a delivered project: new needs from docs/inputs/vN/ merged into IDEA/SPEC, PLAN delta of REQs typed ADDED / MODIFIED / REMOVED, delivered REQs read-only |
IDEA/SPEC/PLAN merged, docs/harper/EXTEND_*.md |
/finalize |
Bring the promoted solution to running and configured (verified in the sandbox, REQ tests not run again) | docs/harper/FINALIZE_REPORT.md, SOLUTION_EVAL.md, scripts/setup_local / start_solution_local |
/kit β /eval β /gate is an iterative control loop per REQ, not a one-shot generation step.
Candidates live under runs/kit/<REQ>/ and are promoted into canonical source roots only after a gate.
Governance principles
- Canonical artifacts win. Methodology companions, skills and agent output are advisory.
- Executors are interchangeable; contracts are not. Cloud and local execution share the same phase contract and are normalized by the orchestrator.
- Agents cannot promote. Local agents write only to the roots allowed by the phase contract and never run Git or promotion.
- The gate is deterministic. Pass/fail comes from executed checks, not from a modelβs judgment.
- The developer is the orchestrator. No phase advances until its output is reviewed.
Two agent operating models
- Developer β CLike β agent. The developer runs a phase; the orchestrator builds an execution package; the extension runs Claude Code or Codex CLI locally; results are normalized and continue through eval and gate. Free Q&A and Coding chat modes can run the same way.
- Agent β CLike. An external agent operates CLike through MCP, dispatching the same commands a developer would type, so it inherits the same governance.
Details: docs/agent-operating-model.md.
Architecture
trust boundary: loopback only Β· service token on every call
βββββββββββββββββββββββββββββ βββββββββββββββββββββββββββββββββ βββββββββββββββββββββββββββββ
β VS CODE EXTENSION βtoken β ORCHESTRATOR (FastAPI) βtoken β MODEL GATEWAY (FastAPI) β
β the only workspace writer βββββββΆβ Harper domain βββββββΆβ provider abstraction β βββΆ cloud providers
β β’ chat UI, slash commands β β β’ phase contracts & packages β β β’ OpenAI / Anthropic β
β β’ confined file writes ββββββββ β’ execution policy ββββββββ β’ OpenAI-compatible β
β β’ Git (non-destructive) β β β’ gate & acceptance integrity β β (e.g. Ollama, optional) β
β β’ local agent actuator β β β’ RAG API Β· MCP server β β β’ embeddings, telemetry β
β β’ operational MCP (opt.) β β β β β
βββββββββββββββββββββββββββββ βββββββββββββββββββββββββββββββββ βββββββββββββββββββββββββββββ
β β evalnet β
βΌ βΌ βΌ
βββββββββββββββββββββββββββββ βββββββββββββββββββββββββββ ββββββββββββββββ
β LOCAL CODING AGENTS β β EVAL SANDBOX β β Qdrant β
β Claude Code Β· Codex CLI β β runs LTC checks; β β vector store β
β own CLI session; write β β no secrets, non-root, β ββββββββββββββββ
β roots from the contract β β read-only, isolated net β
βββββββββββββββββββββββββββββ βββββββββββββββββββββββββββ
| Component | Path | Responsibility |
|---|---|---|
| VS Code extension | extensions/vscode/ |
UI, workspace access, confined writes, local agent execution, Git, RAG collection |
| Orchestrator | orchestrator/ |
Harper phase semantics and definitions (phases/), typed phase contract, cloud prompt composition, local-agent packages, eval/gate, RAG, MCP |
| Gateway | gateway/ |
Model catalog and routing, provider calls, RAG material and output extraction/validation for Harper runs, embeddings, telemetry |
| Configuration | configs/ |
Model catalog (models.yaml), routing profiles |
| Runtime | docker/ |
Local stack (Podman or Docker Compose) |
Further reading: architecture Β· Harper workflow Β· artifacts Β· context sources Β· RAG Β· Git and promotion.
Security model
CLike executes model-generated code and drives agents that write files, so security is part of the design:
- Authenticated, loopback-only services. Every endpoint except
/healthrequires a service token; services fail closed without one, accept only loopback/serviceHostheaders and expose no CORS. - Confinement. Paths from models, agents or requests are confined to their roots (workspace, run directory, telemetry); the extension is the only component that writes the workspace.
- Trusted, isolated evaluation. The gate executes the profile stored in the workspace, never one supplied by the caller, in a sandbox without credentials or access to the other services; the acceptance surface is locked before evaluation and tampering blocks the gate; overrides are audited.
- Least privilege at runtime. Services run as a non-root user; the CLike repository is mounted read-only.
- Non-destructive Git. Only the files of a phase are committed; no branch is rewritten; commit, push, merge and PR automation are opt-in.
See SECURITY.md for the threat model, current limitations and how to report a vulnerability.
Install
Requirements: VS Code 1.85+, Podman 5 with podman-compose (or Docker Compose v2) and a container
VM with at least 4 GB, provider API keys for cloud models, optionally the Claude Code or Codex CLI.
cp .env.example .env # provider keys + CLIKE_API_TOKEN=$(openssl rand -hex 32)
cp docker/.env.example docker/.env # CLIKE_PROJECTS_DIR = host folder containing your projects
cd docker && podman-compose up -d --build # services on 127.0.0.1, wait until (healthy)
code --install-extension ../extensions/vscode/clike-1.10.0.vsix
In VS Code: CLike: Set Service Token (the CLIKE_API_TOKEN value). Full guide, local agents
and the MCP setup for Claude Code / Codex: docs/INSTALL.md.
Get started
Open a project under CLIKE_PROJECTS_DIR, run CLike: Chat (Q&A / Harper / Coding), Harper mode:
/init β /idea β /spec β /plan β ( /kit REQ-xxx β /eval REQ-xxx --fix β /gate REQ-xxx )* β /finalize
next release: /idea --extend β ( /kit β /eval --fix β /gate )* for the new REQs β /finalize
existing project (not built with CLike): /init β /adopt β /idea --extend β β¦
Bringing an existing project into CLike β β every step, from /init in place
to /adopt and the first /idea --extend; the team keeps its layout, commands and process.
/autopilot runs the ( /kit β /eval --fix β /gate )* part unattended β from the chat, MCP or
scripts/clike-autopilot.sh β parks a REQ that needs you and resumes where it was after an
interruption (commands).
With execution = agent the chat is a continuing conversation with Claude Code or Codex
(/agent-model, /agent-session), and Claude Code / Codex can drive CLike through MCP.
Walkthrough, options and troubleshooting: docs/GET_STARTED.md.
Telemetry
Every phase run (cloud or local agent) is recorded per project: model, tokens (cached ones
included), duration and cost. Open http://127.0.0.1:8000/v1/metrics/harper/ui and log in with
CLIKE_API_TOKEN. Local-agent cost is the API-equivalent cost. Details:
telemetry portal.
Extensibility
- Capabilities β project-local skills, packs and design profiles (
.clike/) that PLAN selects per REQ and KIT/EVAL/GATE enforce. β docs/CAPABILITIES.md - Methodology profiles β optional, advisory enrichment of phases, e.g. a profile compatible with BMad Method (analyst, PM, UX, architect, developer, QA, tech-writer roles), without a runtime dependency and without overriding Harper governance. β docs/integrations/bmad
- MCP β a read-only informational server in the orchestrator and an opt-in operational server in the extension, both token-protected. β docs/mcp.md
- Models β declarative catalog and routing in
configs/models.yaml. β setup and runtime
Engineering practice
| Practice | How |
|---|---|
| Reproducible builds | Python 3.12, per-service pyproject.toml + uv.lock; npm ci with lockfile |
| Behavioural safety net | Golden snapshots of the phase boundary (orchestrator β gateway β provider) |
| Security regression suites | Authentication, confinement, Git safety (tests on real repositories) |
| Static analysis | ESLint with a frozen baseline: existing debt can only shrink |
| Repository hygiene | Pre-commit and CI check: no telemetry, secrets or private notes in the public repo |
| Continuous integration | GitHub Actions: hygiene, orchestrator, gateway, extension (Linux, Windows) |
Developer guide: docs/development.md.
Research context
CLike combines three lines of work and investigates how to make them governable in practice:
- Harper-style iterative generation β idea β spec β plan β kit in short, verifiable loops (Harper Reed β LLM codegen workflow).
- Vibe coding β intent- and outcome-level development with cognitive offloading to AI (Gartner).
- AI-native software engineering β agentic workflows with human-in-the-loop governance, grounding and automated validation (Gartner).
Open research questions the project works on:
- How to keep acceptance criteria independent from the implementation produced by the same agent.
- How to bound autonomous KIT β EVAL repair loops (iterations, cost, escalation) without losing control.
- How to make the same governed lifecycle usable from inside native coding agents (skills, MCP, CI gates).
- How to measure delivery outcomes (lead time, first-pass gate rate, cost per requirement) rather than code volume.
Roadmap
| Horizon | Focus |
|---|---|
| M2 | Gate in an isolated sandbox, acceptance lock with tamper detection and audited overrides (done); provider and functional fixes |
| M3 | Typed, versioned phase contract; one definition per phase rendered for cloud and agents |
| Next | Native agent chat with streaming, inline approvals and runtime policy enforcement Β· Harper usable from Claude Code / Codex (skills, MCP, CLI) and as a CI gate Β· autonomous KIT β EVAL loops Β· parallel REQs on Git worktrees Β· taking over projects not built with CLike inside /idea --extend Β· traceability and delivery metrics |
Documentation
| Topic | Document |
|---|---|
| Overview and reading order | CLike at a glance, docs/README.md |
| The chat UI (cockpit, run card) | docs/chat-ui.md |
| Getting operational | Bringing an existing project into CLike, HOWTO, Harper run walkthrough, project via MCP, /init β /finalize with BMAD from Claude Code |
| Concepts | architecture, Harper workflow, agent operating model, artifacts, quality and granularity, estimating with CLike |
| Reference | commands, API, MCP, capabilities |
| Operations | setup and runtime, Git and promotion, telemetry portal |
| Development | developer guide, CHANGELOG, SECURITY |
| Community | CONTRIBUTING, Code of Conduct, SUPPORT, Discussions |
Contributing
Issues, ideas and pull requests are welcome: start from CONTRIBUTING.md. Questions go to Discussions, security problems are reported privately as described in SECURITY.md.
License
Apache License 2.0 β see LICENSE and NOTICE.
CLike on, code on.
BMadβ’ and BMad Methodβ’ are trademarks of BMad Code, LLC; CLike is not affiliated with or endorsed by BMad Code, LLC.