Files

T

ciagent f1c55ca79b docs(audit): fix .ciagent/ file discipline issues

Audit findings addressed:
- PROJECT.md: add 'What This Is' and 'Key Decisions' sections (per audit Step 2)
- ARCHITECTURE.md: add internal/jobspec (HCL parser) and internal/model (domain types) to system diagram and component details
- PLANS.md: expand REQ coverage lines for Phase 1 and Phase 3 to include all REQ-IDs the work actually delivers (REQ-003 offline-first, REQ-008 slog, REQ-010 --json, REQ-020 hashicorp/hcl)

---ci---
project: orca
phase: 0
milestone: v0.1
status: fix
---/ci---

2026-06-03 20:14:03 +00:00

4.2 KiB

Raw Blame History

Project: Orca

What This Is

A minimalist, offline-first, CLI-first orchestration engine inspired by HashiCorp Nomad, prioritizing stability, security, and simplicity over feature richness. Single-binary distribution, no container runtime, no cloud dependencies, no K8s-level complexity.

Vision

A minimalist, offline-first, CLI-first orchestration engine inspired by HashiCorp Nomad, prioritizing stability, security, and simplicity over feature richness.

Objective

Build a lightweight system to manage and execute workloads across a set of nodes, keeping complexity far below that of Kubernetes.

Requirements

CLI First: Primary interaction through a CLI tool.
Offline First: Functional without constant internet connectivity.
AI First: Designed to be easily discoverable and manageable by AI agents.
Stability & Security: Prioritize security fixes and bug fixes over new features.
Language: Written in Go 1.25+.
Simplicity: Minimalist implementation, avoiding the "K8s complexity trap".

Constraints

No web UI as a primary requirement.
Must not implement K8s-level complexity.
Feature development must move slowly to ensure stability.
Only CI system allowed: CoreCI (git.cloudinit.dev/coreci/coreci).
Gitea remote: git.cloudinit.dev/coreci/orca.

Clarified Decisions (D-series, full autonomy)

ID	Question	Decision	Rationale	Confidence
D-001	Single binary or multi-binary distribution?	Single binary	Simpler distribution; subcommands baked into one `orca` binary. Aligns with simplicity pillar.	0.95
D-002	Local state store technology?	modernc/sqlite (pure Go, CGO-free)	Cross-compile friendly, no CGO dependency, single file on disk, mature.	0.92
D-003	Inter-node communication?	Embedded HTTP (net/http) over loopback, mTLS for cross-node	No external RPC framework needed for v0.1. HTTP suffices.	0.85
D-004	Scheduling algorithm for v0.1?	Single-node only (no scheduling)	Multi-node scheduling is out of scope for v0.1. Tasks run on the node they're submitted to.	0.90
D-005	CLI output format?	Human-readable by default, `--json` flag for machine consumption	Serves both humans and AI agents.	0.95
D-006	Job/task definition format?	HCL or YAML in `.hcl`/`.yaml` files	Familiar to Nomad/HashiCorp users; simpler than JSON for humans.	0.88
D-007	Authentication?	mTLS for v0.1, token-based deferred	mTLS is the most secure default. Tokens can be added later if needed.	0.80
D-008	Container runtime?	Direct process execution (no container runtime) for v0.1	Avoids the Docker/container dependency. Pure process management.	0.85
D-009	Configuration file location?	`~/.orca/config.hcl` and `/etc/orca/orca.hcl`	Standard XDG-style paths.	0.90
D-010	Logging format?	Structured JSON via `log/slog`	Native Go 1.21+ slog, no external dependency.	0.95

Out of Scope

Full-blown Kubernetes-compatible API.
Complex cloud-provider integrations.
GUI-based management consoles.
Multi-node scheduling.
Container runtime integration.
Service mesh / sidecar injection.
Auto-scaling / horizontal pod autoscaler.

Key Decisions

Single binary (D-001): one orca binary with subcommands — no multi-binary distribution.
modernc/sqlite (D-002): CGO-free SQLite for state — single file, cross-compile friendly.
Embedded HTTP over loopback (D-003): net/http for v0.1; mTLS for cross-node (REQ-011, REQ-023 deferred to v0.2).
Single-node only (D-004): no multi-node scheduling in v0.1 (deferred to v0.2).
Human-readable + --json (D-005): both outputs supported from the start.
HCL/YAML specs (D-006): familiar to Nomad/HashiCorp users.
mTLS for v0.1, tokens deferred (D-007): most secure default; tokens if needed later.
Direct process execution (D-008): no container runtime — pure process management.
~/.orca/config.hcl and /etc/orca/orca.hcl (D-009): standard XDG-style paths.
Structured JSON via log/slog (D-010): native Go 1.21+ slog, no external dependency.

See Clarified Decisions below for full table with confidence scores.

4.2 KiB Raw Blame History