freemo
5a24b5bdf2
New skill covering every architectural concept, entity, workflow, CLI command, and design decision from docs/specification.md (47,181 lines read in full). Explains WHAT the system is intended to build. SKILL.md (1,282 lines) — 18 decision trees: - 'What am I working on?' master routing tree - 'What is a Plan?' — 4 phases, reversion rules, hierarchy, decision tree - 'How does a plan run?' — step-by-step Action→Strategize→Execute→Apply - 'What is a Decision?' — 10 types, data model, dual tree+DAG structure, timing by phase, decision recording protocol - 'How do I correct a plan?' — revert vs append modes, Strategize vs Execute correction mechanics, affected subtree computation - 'What is an Invariant?' — 4 scopes, precedence chain (plan>action> project>global), non-overridable globals, Invariant Reconciliation Actor - 'What is an Actor?' — LLM vs graph types, Jinja2+env-var preprocessing, specialized roles (strategy/execution/estimation/invariant) - 'What is a Tool?' — 4 sources, capability metadata, 4-stage lifecycle, resource bindings and slots, anonymous tools, metadata overrides - 'What is a Validation?' — Tool subtype, always read-only, required vs informational modes, 3 attachment scopes, wrapping existing tools - 'What is a Skill?' — composition patterns, includes, tool overrides - 'What is a Resource?' — physical vs virtual, 34+ built-in types, DAG, type inheritance, 5-sandbox strategies, 6-level execution env routing, devcontainer auto-discovery and lazy activation - 'What is a Project?' — resource linking, multi-project plans, context config, execution environment - 'Which automation profile applies?' — 8 built-in profiles, 11 flags, Safety Profile, Automation Guard, Semantic Escalation, progressive trust - 'How does naming work?' — namespace format, types, ULID vs name identity - 'Which CLI command do I use?' — every command group with key flags - 'What is the architecture?' — 4 layers, 2 deployment modes, A2A protocol (full method routing, error codes, streaming), DI container - 'What is the ACMS?' — UKO, CRP, 10-slot pipeline, hot/warm/cold tiers - 'Which milestone am I in?' — v3.2.0–v3.8.0 status + cross-milestone invariants - Key Numbers table (35 entries) Reference files (1,974 lines across 9 files): - plan-lifecycle: phase mechanics, decision tree schema, checkpoint triggers, child plan execution modes, merge strategies, plan identity fields - entities: data models for Plan, Decision, Action, Session, Invariant, AutomationProfile, SafetyProfile, AutomationGuard, Namespace - architecture: 4-layer diagram, deployment modes, complete A2A method routing tables (standard + plan + registry + context + sync + health), streaming events, authentication, error taxonomy, full tech stack - automation-profiles: threshold table for all 8 built-in profiles, use cases, Semantic Escalation algorithm, custom profile YAML - actors-tools-skills: Actor/Tool/Validation/Skill YAML schemas with complete annotated examples, Jinja2 filter reference, LSP integration detail, LSPToolAdapter, actor context precedence - resources: complete resource type hierarchy (all 34+ types), sandbox strategies, type inheritance rules, execution environment routing, devcontainer integration, CLI usage - acms: UKO 4-layer ontology, CRP, 10-slot Context Assembly Pipeline with per-slot component names, hot/warm/cold eviction rules, skeleton compression, context view configuration - milestones: v3.2.0–v3.8.0 deliverables, architectural constraints, and definitions of done; cross-milestone quality gates and invariants - cli-commands: complete CLI reference for all command groups with all flags: plan, action, session, project, actor, skill, tool, validation, resource, invariant, automation-profile, lsp, config, utility ISSUES CLOSED: #0
CLI Commands — Complete Reference
Global Options
Apply to every command:
agents [--data-dir PATH] [--config-path PATH] [--format rich|color|table|plain|json|yaml]
[--help|-h] [--version] [--install-completion [SHELL]] [--show-completion [SHELL]]
[-v...] <COMMAND> [<ARGS>...]
--data-dir PATH: Override data directory (database, caches, sessions, logs)--config-path PATH: Override config file path--format FORMAT: Output rendering format (default: rich, fromcore.formatconfig)-v: Increase verbosity (repeatable): -v=ERROR, -vv=WARN, -vvv=INFO, -vvvv=DEBUG, -vvvvv=TRACE
Output Formats
| Format | Description | Use For |
|---|---|---|
rich |
Modern rich CLI with animation, spinners, progress bars | Interactive terminal (default) |
color |
Plain text with ANSI color codes | Color-capable terminals |
table |
ASCII box-drawing tables with color | Structured visual output |
plain |
Plain text, no color, no non-ASCII | Piping, logs, non-terminal consumers |
json |
Structured JSON | Scripts, CI/CD, programmatic consumption |
yaml |
Structured YAML | Configuration, programmatic consumption |
Plan Commands
# List plans (filterable)
agents plan list [--phase PHASE] [--state STATE] [--project PROJECT] [--action ACTION] [<REGEX>]
# Create plan (Action → Strategize)
agents plan use [--automation-profile PROFILE]
[--invariant INVARIANT]...
[--strategy-actor ACTOR] [--execution-actor ACTOR]
[--estimation-actor ACTOR] [--invariant-actor ACTOR]
[--execution-environment RESOURCE_NAME]
[--execution-env-priority fallback|override]
[--arg/-a name=value]...
<ACTION> <PROJECT>...
# Phase transitions
agents plan execute <PLAN_ID>
agents plan apply [--yes|-y] <PLAN_ID>
# Status and inspection
agents plan status <PLAN_ID>
agents plan tree [--show-superseded] <PLAN_ID>
agents plan explain [--show-context] [--show-reasoning] <DECISION_ID>
agents plan diff (--correction <CORRECTION_ATTEMPT_ID> | <PLAN_ID>)
agents plan artifacts <PLAN_ID>
agents plan errors <PLAN_ID>
# Correction
agents plan correct --mode (revert|append) (--guidance|-g) <GUIDANCE>
[--dry-run] [--yes|-y] <DECISION_ID>
# Checkpoint rollback
agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID>
# Inject guidance mid-execution
agents plan prompt <PLAN_ID> <GUIDANCE>
# Cancel
agents plan cancel [(--reason|-r) <REASON>] <PLAN_ID>
Action Commands
agents action create --config|-c <CFG_FILE>
agents action list [(--namespace|-n) NS] [(--state|-s) STATE] [<REGEX>]
agents action show <ACTION_NAME>
agents action archive <ACTION_NAME>
Session Commands
agents session create [--actor ACTOR]
agents session list
agents session show <SESSION_ID>
agents session delete [--yes|-y] <SESSION_ID>
agents session export [(--output|-o) FILE] <SESSION_ID>
agents session import (--input|-i) FILE
agents session tell --session <SESSION_ID> [--actor ACTOR] [--stream] <PROMPT>
Project Commands
agents project create [(--description|-d) DESC] [--resource RESOURCE]...
[--invariant INVARIANT]... [--invariant-actor ACTOR] <NAME>
agents project link-resource [--read-only] <PROJECT> <RESOURCE>
agents project unlink-resource [--yes|-y] <PROJECT> <RESOURCE_NAME>
agents project list [(--namespace|-n) NS] [<REGEX>]
agents project show <PROJECT>
agents project delete [--force|-f] [--yes|-y] <NAME>
# Context configuration
agents project context set [--view strategize|execute|apply|default]
[--include-resource RESOURCE]...
[--exclude-resource RESOURCE]...
[--include-path GLOB]...
[--exclude-path GLOB]...
[--hot-max-tokens N]
[--warm-max-decisions N]
[--cold-max-decisions N]
[--query-limit N]
[--max-file-size BYTES]
[--max-total-size BYTES]
[--summarize|--no-summarize]
[--summary-max-tokens N]
[--strategy STRATEGY]...
[--default-breadth N]
[--default-depth INT_OR_NAME]
[--depth-gradient HOP:INT_OR_NAME]...
[--skeleton-ratio FLOAT]
[--temporal-scope current|recent|all]
[--auto-refresh|--no-auto-refresh]
[--execution-environment RESOURCE_NAME]
[--execution-env-priority fallback|override]
[--clear] <PROJECT>
agents project context show [--view strategize|execute|apply|default] <PROJECT>
agents project context inspect [--view ...] [--strategy S] [--focus UKO_URI]...
[--breadth N] [--depth INT_OR_NAME] <PROJECT>
agents project context simulate [--view ...] [--budget TOKENS]
[--focus UKO_URI]... [--strategy S]... <PROJECT>
Actor Commands
agents actor run [(--output|-o) OUTPUT_FILE] [-v...] [--unsafe|-u]
[--context CONTEXT_NAME] [--context-dir CONTEXT_PATH]
[--load-context LOAD_CONTEXT_NAME]
[(--temperature|-t) TEMP] [--allow-rxpy-in-run-mode]
[--skill SKILL]... <NAME> <PROMPT>
agents actor add --config|-c <FILE> [--update]
agents actor remove <NAME>
agents actor list
agents actor show <NAME>
# Actor context management
agents actor context remove [--yes|-y] (--all|-a | <NAME>)
agents actor context list [<REGEX>]
agents actor context show <NAME>
agents actor context export (--output|-o) FILE <NAME>
agents actor context import [--update] (--input|-i) FILE [<NAME>]
agents actor context clear [--yes|-y] (--all|-a | <NAME>)
Skill Commands
agents skill add --config|-c <FILE> [--update]
agents skill remove [--yes|-y] <NAME>
agents skill list [(--namespace|-n) NS] [--source SOURCE]
agents skill show <NAME>
agents skill tools <NAME> # lists all tools in skill (including transitive)
Tool Commands
agents tool add --config|-c <FILE> [--update]
agents tool remove [--yes|-y] <NAME>
agents tool list [(--namespace|-n) NS] [--source SOURCE] [--type tool|validation] [<REGEX>]
agents tool show <NAME>
Validation Commands
agents validation add --config|-c <FILE> [--update]
agents validation attach [--project PROJECT | --plan PLAN_ID]
<RESOURCE> <VALIDATION> [<ARGS>...]
agents validation detach [--yes|-y] <ATTACHMENT_ID>
# list/show/remove via: agents tool list --type validation, agents tool show, agents tool remove
Resource Commands
# Resource type management
agents resource type add --config|-c <FILE> [--update]
agents resource type remove [--yes|-y] <NAME>
agents resource type list [<REGEX>]
agents resource type show <NAME>
# Resource CRUD
agents resource add [(--description|-d) DESC] [--update] <TYPE> <NAME> [type-specific-flags...]
agents resource remove [--yes|-y] <NAME>
agents resource list [--all] [(--type|-t) TYPE]
agents resource show <RESOURCE>
# Resource exploration
agents resource inspect [--tree] [--file PATH] <RESOURCE>
agents resource tree [(--depth|-d) N] [(--type|-t) TYPE] <RESOURCE>
# DAG management
agents resource link-child <PARENT> <CHILD>
agents resource unlink-child [--yes|-y] <PARENT> <CHILD>
# Container management
agents resource stop <NAME>
agents resource rebuild <NAME>
Invariant Commands
agents invariant add [--global] [(--project|-p) PROJECT] [--plan PLAN_ID]...
[--action ACTION]... [--non-overridable] <INVARIANT_TEXT>
agents invariant list [--global] [(--project|-p) PROJECT] [--plan PLAN_ID]
[--action ACTION] [--effective] [<REGEX>]
agents invariant remove [--yes|-y] <INVARIANT_ID>
Automation Profile Commands
agents automation-profile add --config|-c <FILE> [--update]
agents automation-profile remove [--yes|-y] <NAME>
agents automation-profile list [<REGEX>]
agents automation-profile show <NAME>
LSP Commands
agents lsp add --config|-c <FILE> [--update]
agents lsp remove [--yes|-y] <NAME>
agents lsp list [(--namespace|-n) NS] [--language LANG]
agents lsp show <NAME>
agents lsp serve [--log-level LEVEL]
Config Commands
agents config set <key> <value>
agents config get <key>
agents config list [--filter-values REGEX] [<REGEX>]
Utility Commands
agents version # print CLI version + dependencies
agents info # show runtime config and status
agents diagnostics # run health checks (config, providers, filesystem)
agents init [--yes|-y] # first-time setup