@agentprojectcontext/apx 1.80.2 → 1.89.1

package/src/core/runtime-skills/apx-routine/SKILL.md

@@ -13,11 +13,18 @@ A scheduled APX task. Scheduler ticks every 5s. Each routine has a `kind`, `sche
 |---|---|---|
 | `heartbeat` | no | "Still alive" marker. No LLM. |
 | `shell` | no | Pure shell. Stdout captured. |
-| `exec_agent` | **no** | Loads agent prompt, sends `spec.prompt`, returns text. Single LLM call. |
+| `exec_agent` | **agent allowlist** | Loads that project agent and runs `spec.prompt`. By default the agent uses its own resolved tools (its `tools:` field, or the broad capability default when it declares none). Persists a conversation. A **non-empty** routine `allowed_tools` overrides the card. For the one-shot text path (no tools at all), set `spec.no_tools: true` — see the gotcha below. |
+| `watch` | **agent allowlist** | Deterministic detection first, then a model judgement step over `spec.prompt`. A watcher, not a cron+LLM. Needs `spec.prompt`. |
 | `super_agent` | **all** | Default agent with full tool registry. Multi-iteration loop. |
-| `telegram` | n/a | Sends hardcoded text via Telegram plugin. |
+| `telegram` | n/a | Sends hardcoded text via Telegram plugin. `spec.text` is the message body — the automation header is NOT prepended to it. |
 
-Rule: text from model → `exec_agent`; orchestration (MCPs, files, multi-agent) → `super_agent`; pure shell → `shell`; fixed Telegram poke → `telegram`.
+Rule: a project agent that must *do* work (read files, Asana, compact a ledger) → `exec_agent`; orchestration as the super-agent → `super_agent`; text-only + shell delivery → `exec_agent` with `spec.no_tools: true`; pure shell → `shell`; fixed Telegram poke → `telegram`.
+
+### `allowed_tools` vs `no_tools` (read before you copy a skeleton)
+
+- `allowed_tools` **non-empty** → overrides the agent's card for this routine.
+- `allowed_tools: []` → **no override; the agent runs with its OWN resolved tools.** This is NOT "no tools" — and `[]` is exactly what `apx routine add` writes when you pass no `--allowed-tools`, so an ordinary create already gives the agent its tools.
+- `spec.no_tools: true` → the deliberate opt-out: a single text-only call, no tools, for the "write one sentence, `post_commands` deliver it" pattern.
 
 ## Schedule grammar
 
@@ -40,7 +47,18 @@ Rule: text from model → `exec_agent`; orchestration (MCPs, files, multi-agent)
 }
 ```
 
-Pipeline: `pre_commands` run sequentially → combined stdout becomes `{{pre_output}}` in `spec.prompt` and `$APX_PRE_OUTPUT` (plus `$APX_PRE_OUTPUT_FILE` for big payloads) → handler runs, result becomes `$APX_LLM_OUTPUT` → `post_commands` run.
+Pipeline: `pre_commands` run sequentially → combined stdout becomes `{{pre_output}}` in `spec.prompt` / `spec.text` and `$APX_PRE_OUTPUT` (plus `$APX_PRE_OUTPUT_FILE` for big payloads) → handler runs, result becomes `$APX_LLM_OUTPUT` → `post_commands` run. `{{pre_output}}` is always substituted — with no pre_commands it renders empty, never as literal braces.
+
+## Automation header (native — don't hand-roll the date)
+
+The runner prepends a native **automation header** to the top of `spec.prompt` on every LLM-backed run (`core/routines/header.js`, built in `core/routines/runner.js`). It carries: routine name + id, the routine's memory path, `last_run_at` and this run's start — each clock given twice, machine-friendly (ISO + epoch ms, UTC) and human-friendly in the owner's `config.user.timezone` / `.locale`.
+
+This **replaces the old `echo "…date…"` pre_command + `{{pre_output}}` trick** for "what time / day is it". Do NOT add a shell pre_command just to feed the model the date — it already opens on who it is and what "now" is. The header is NOT prepended to a `telegram` routine's `spec.text` (that string is the message body, sent verbatim).
+
+## Iteration budget
+
+- A routine that **reports to Telegram** (its `post_commands` send via Telegram, so `send_telegram` is auto-suppressed) uses `super_agent.telegram_max_iters` (default `TELEGRAM_TOOL_ITERS`, a high runaway backstop) and normally runs until work is done.
+- Any **other** routine runs effectively **uncapped** to completion (`super_agent.routine_max_iters`, default `ROUTINE_UNCAPPED_TOOL_ITERS`): background work nobody is watching (Magui filling a backlog) must finish, not get cut at the chat budget. Only the `post_command` Telegram sink marks a routine telegram-bound — a routine whose *agent* sends a summary at the end is still uncapped.
 
 ## Anti-example: double-reply
 
@@ -52,12 +70,12 @@ Pipeline: `pre_commands` run sequentially → combined stdout becomes `{{pre_out
 }
 ```
 
-Sends **two** messages: one from agent's `send_telegram` tool, one from `post_commands`. The runner auto-suppresses `send_telegram` when post contains `apx telegram send`, but the clean fix is `exec_agent`:
+Sends **two** messages: one from agent's `send_telegram` tool, one from `post_commands`. The runner auto-suppresses `send_telegram` when post contains `apx telegram send`, but the clean fix is `exec_agent` with tools off (`spec.no_tools: true` — NOT `allowed_tools: []`, which leaves the agent's tools on):
 
 ```json
 {
   "kind": "exec_agent",
-  "spec": { "agent": "default", "prompt": "The weather is {{pre_output}}. One friendly sentence." },
+  "spec": { "agent": "default", "no_tools": true, "prompt": "The weather is {{pre_output}}. One friendly sentence." },
   "post_commands": ["apx telegram send \"$APX_LLM_OUTPUT\""]
 }
 ```
@@ -66,12 +84,12 @@ Sends **two** messages: one from agent's `send_telegram` tool, one from `post_co
 
 ```bash
 # Always pin --project; never use default for real ones
-apx routine list --project iacrmar
-apx routine get  weather-bariloche --project iacrmar
+apx routine list --project acme
+apx routine get  weather-bariloche --project acme
 
 # Create — exec_agent + shell delivery
 apx routine add weather-bariloche \
-  --project iacrmar \
+  --project acme \
   --kind exec_agent \
   --schedule "every:24h" \
   --spec '{"agent":"default","prompt":"The weather is {{pre_output}}. One friendly sentence."}' \
@@ -80,17 +98,17 @@ apx routine add weather-bariloche \
 
 # Create — super-agent with tools
 apx routine add daily-status \
-  --project iacrmar \
+  --project acme \
   --kind super_agent \
   --schedule "0 9 * * *" \
   --spec '{"prompt":"List projects with pending tasks and send me a short summary via Telegram."}' \
   --permission-mode automatico
 
 # Toggle / run / remove
-apx routine enable  weather-bariloche --project iacrmar
-apx routine disable weather-bariloche --project iacrmar
-apx routine run     weather-bariloche --project iacrmar     # force-trigger now
-apx routine remove  weather-bariloche --project iacrmar
+apx routine enable  weather-bariloche --project acme
+apx routine disable weather-bariloche --project acme
+apx routine run     weather-bariloche --project acme     # force-trigger now
+apx routine remove  weather-bariloche --project acme
 ```
 
 ## `--project` is non-negotiable
@@ -99,7 +117,7 @@ Routines live in `~/.apx/projects/<apxId>/routines.json`. Without `--project`, t
 
 ## `skip_prompt_on`
 
-Gates the LLM call based on `pre_commands` (`shouldSkipPrompt` in `host/daemon/routines.js`). Post-commands always run.
+Gates the LLM call based on `pre_commands` (`shouldSkipPrompt` in `src/core/routines/runner.js`). Post-commands always run.
 
 | Value | Skips LLM when… |
 |---|---|
@@ -112,16 +130,21 @@ Gates the LLM call based on `pre_commands` (`shouldSkipPrompt` in `host/daemon/r
 ## Debugging
 
 ```bash
-apx routine history weather-bariloche --project iacrmar    # last runs
+apx routine history weather-bariloche --project acme    # last runs
 apx log -f                                                  # tail unified log
 apx messages tail --channel routine -n 20                   # routine-channel messages
+
+# Routine memory (the file named in the automation header)
+apx routine memory show weather-bariloche --project acme    # read it
+apx routine memory add  weather-bariloche "note" --project acme   # append a note
+apx routine memory path weather-bariloche --project acme    # print its path
 ```
 
 "Sends nothing" usually means: `enabled: false`, `next_run_at` in the future, or empty LLM text (check `apx messages` or `result.text`).
 
 ## Don't
 
-- Use `super_agent` when `exec_agent` would do — it loops, calls tools, costs more.
+- Use `super_agent` when a project agent should own the work — `exec_agent` runs that agent with tools and the chat lands under their name.
 - Write `apx telegram send` inside a `super_agent` prompt — agent calls `send_telegram` AND post_commands fire. Pick one.
 - Hardcode model names in `spec` without reason — routines inherit `super_agent.model` (with router fallback).
 - Put credentials in `spec`. Use `~/.apx/config.json` engines and reference by provider.

package/src/core/runtime-skills/apx-runtime/SKILL.md

@@ -1,23 +1,33 @@
 ---
 name: apx-runtime
-description: Delegate a task to an external coding CLI (claude-code, codex, opencode, aider, cursor-agent, gemini-cli, qwen-code) via `apx run`. APX builds the system prompt, spawns the CLI, captures the result. Load when delegating to another AI tool.
+description: Delegate a task to an external coding CLI (claude-code, codex, opencode, aider, cursor-agent, gemini-cli, qwen-code, antigravity) via `apx run`. The APX agent is optional — pass-through runs the CLI as itself, `-a <agent>` wraps it in that agent's system prompt. Load when delegating to another AI tool, or when confused about the agent argument.
 ---
 
 # apx-runtime
 
-A "runtime" is an external AI coding CLI that APX invokes headlessly. APX builds the agent's system prompt, spawns the CLI with the right flags, captures stdout (and the external session id when available), and stores run metadata as a session file under `~/.apx/projects/<apxId>/agents/<slug>/sessions/` (never committed). Some flows link to the engine's own transcript path.
+A "runtime" is an external AI coding CLI that APX invokes headlessly. APX spawns the CLI with the right flags, captures stdout (and the external session id when available), and stores run metadata as a session file under `~/.apx/projects/<apxId>/agents/<slug>/sessions/` (never committed). Some flows link to the engine's own transcript path.
+
+## The agent is OPTIONAL — and it is not "the CLI's agent"
+
+`apx run` delegates a prompt to an external CLI (claude-code, codex, …) that **has its own agency**. An APX agent does one thing here: its `buildAgentSystem()` output becomes the CLI's system prompt. It is a wrapper, not something Claude "uses."
+
+- **No agent → pass-through.** `apx run --runtime claude-code "<prompt>"` hands the prompt to the CLI with **no APX system prompt** — Claude/Codex runs as itself. This is the right form when you just want to delegate a task to the tool. Don't invent an agent to do it.
+- **With an agent → wrapped.** `apx run -a <agent> --runtime … "<prompt>"` when you want an APX persona/instructions (a project reviewer, a house style) to shape the run. Use it only when that wrapping is the point.
+
+(`apx exec` is the sibling for APX's OWN in-process engine — there `-a <agent>` is likewise optional and defaults to the super-agent. `apx run` is specifically for spawning an external CLI.)
 
 ## Supported runtimes
 
 | id | binary | Headless flag |
 |---|---|---|
 | `claude-code`   | `claude`        | `-p "<prompt>" --append-system-prompt "<sys>" --output-format json` |
-| `codex`         | `codex`         | `exec "<prompt>"` (works outside git repos) |
-| `opencode`      | `opencode`      | non-interactive mode |
-| `aider`         | `aider`         | `--message "<prompt>" --no-stream` |
+| `codex`         | `codex`         | `exec "<prompt>" --sandbox workspace-write --skip-git-repo-check --json` |
+| `opencode`      | `opencode`      | `run "<prompt>"` (non-interactive) |
+| `aider`         | `aider`         | `--message "<prompt>" --yes-always --no-auto-commits` |
 | `cursor-agent`  | `cursor-agent`  | headless print mode |
 | `gemini-cli`    | `gemini`        | headless prompt mode |
-| `qwen-code`     | `qwen-code`     | system prompt passed separately |
+| `qwen-code`     | `qwen`          | `--output-format text --approval-mode yolo "<prompt>"` |
+| `antigravity`   | `agy`           | `agy -p "<prompt>"` (headless). Falls back to the `antigravity-ide` GUI, which can't return a result to stdout. |
 
 `apx env detect` reports which are installed and reachable.
 
@@ -27,19 +37,41 @@ A "runtime" is an external AI coding CLI that APX invokes headlessly. APX builds
 apx env detect          # which runtimes are installed
 apx env list            # alias
 
-apx run reviewer --runtime claude-code "Review the diff in src/host/daemon/api/ for memory leaks"
-apx run scratch  --runtime codex       "Refactor parseAgentsMd to use a state machine"
-apx run scratch  --runtime opencode    "<prompt>"
-apx run scratch  --runtime codex --timeout 300 "<prompt>"   # cap (seconds)
-apx run scratch  --runtime codex -      # prompt from stdin (large prompts)
+# Pass-through — just delegate to the CLI (no APX agent). The common case.
+apx run --runtime claude-code "Review the diff in src/host/daemon/api/ for memory leaks"
+apx run --runtime codex        "Refactor parseAgentFile to use a state machine"
+apx run --runtime codex --timeout 300 "<prompt>"   # cap (seconds)
+apx run --runtime codex -                          # prompt from stdin (large prompts)
+
+# Wrapped — shape the run with an APX agent's system prompt.
+apx run -a reviewer --runtime claude-code "Review this repo"
 ```
 
 Behavior:
 1. APX picks project from `--project` or cwd.
-2. Reads agent's `AGENT.md` + memory + skills; builds system prompt with `buildAgentSystem({ invocation: "runtime", runtime: "<id>" })`.
+2. **If `-a <agent>` was given**, reads that agent's definition + memory + skills and builds a system prompt with `buildAgentSystem(project, agent, { invocation: "runtime", runtime: "<id>" })`. **No agent → no system prompt (pass-through).**
 3. Spawns CLI with the right flags; cwd = project path.
 4. Captures stdout. If runtime printed `APC_RESULT: <value>`, that's the structured result; else first 200 chars of stdout.
-5. Writes `~/.apx/projects/<apxId>/agents/<slug>/sessions/<YYYY-MM-DD>-<id>.md` with frontmatter linking back to the external transcript when available.
+5. Writes a session file under `~/.apx/projects/<apxId>/agents/<slug>/sessions/` — `<slug>` is the agent, or the runtime id for a pass-through run.
+
+## `apx run` delegates; `apx send` converses
+
+`apx run` is a ONE-SHOT: the CLI starts cold, does the task, exits. When you want
+a back-and-forth with the CLI instead — ask, read the answer, ask again — address
+it as an a2a peer:
+
+```bash
+apx send <you> opencode "<message>" --deliver
+apx send <you> "opencode#review" "<message>" --deliver   # a second, separate thread
+```
+
+The peer answers on the a2a channel and CONTINUES ITS OWN SESSION between turns
+(`claude -p --resume`, `codex exec resume`, `opencode run --session`); APX keeps
+the id on the thread. So the second message costs one message, not a re-read of
+everything that came before. See the **apx** skill for the full addressing rules.
+
+Use `apx run` when you want the task done and the result back. Use `apx send`
+when the exchange has more than one turn.
 
 ## Resuming an external session
 
@@ -57,7 +89,7 @@ session_id: abc123
 Full resume/get/continue/summarise lives in the **`apx-sessions`** skill. Quick paths:
 
 ```bash
-apx sessions list --engine claude --project iacrmar
+apx sessions list --engine claude --project acme
 apx session resume <id>                          # auto-detects engine
 apx session resume <id> --continue               # spawn native CLI to keep going
 apx session resume <id> --summary                # super-agent summary
@@ -67,6 +99,84 @@ apx session get <id> --any --full                # or --engine claude --tail 16k
 
 See `apx-sessions` for full flag reference, collision handling, and daemon-vs-no-daemon matrix.
 
+## Async relay — reply back into a coding session
+
+Two agents that don't share a live process still need to talk both ways: a coding
+CLI (Claude Code, Codex, …) finishes and asks an APX agent something, the agent
+relays it to the user, the user answers, and the answer has to land back in the
+**same** coding session — with its full context intact. The daemon **cannot**
+inject into a live interactive CLI process, so the model is **mailbox + resume**,
+not a live socket: each round-trip is one headless resume of the session.
+
+**The whole convention is one line: identify your session when you message the
+agent.** A coding session tells the agent who to answer by including its engine
+and session id in the message body — nothing more:
+
+```
+engine=claude session=<your-session-id>
+```
+
+That's the "return address". Any APX agent, on seeing it, knows how to reply.
+
+**The return leg** — how an agent (or you, testing) answers a coding session:
+
+```bash
+# Headless: inject one message into the session's transcript (full context) and
+# capture its reply on stdout. Implies --continue. Claude only for now.
+apx session resume <session-id> --continue --msg "the owner says: go ahead with the tests, don't touch login"
+```
+
+The reply the woken session produces comes back on stdout — the agent relays that
+to the user, and the loop can go around again.
+
+**For an APX agent** (this is a general capability, not one agent's prompt hack):
+when a message carries `engine=claude session=<id>` and the user later answers it,
+run `apx session resume <id> --continue --msg "<user's reply>"` to hand the answer
+back. If you can't resolve the session or the resume fails, tell the user — never
+swallow it.
+
+**If you can't determine your own session id**, say so in the message instead of
+guessing — the agent then starts a fresh run rather than a true resume, and the
+user knows context won't carry.
+
+**The outbound leg** (coding CLI → agent) goes on the **a2a channel**, so the
+agent sees it as agent-to-agent, not as the user typing:
+
+```bash
+apx send <engine> <agent> "…question… engine=claude session=<id>" --deliver --project <name>
+```
+
+The sender does not need to be a registered agent — a coding CLI passes its
+engine name (`claude`, `codex`). If the recipient slug exists in several projects,
+`apx send` lists them; pass `--project`. `apx agent list --all` shows every agent
+with its project. Do NOT use `apx exec` for the hand-off — that posts on the user
+channel (the agent reads it as if the user spoke). `--msg` headless delivery on
+the return leg is claude-only today; other engines print "not supported yet". See
+the **claude-code** skill for the coding-CLI side.
+
+### a2a etiquette — never message the owner directly
+
+An a2a message is another AGENT talking, not the owner. The daemon enforces this
+in the a2a reply prompt, and you should follow it in fuller turns too:
+
+- **Don't ping the owner from an a2a turn.** No `apx telegram send`, no direct
+  owner message. Whether the owner hears about it — and when — is the
+  orchestrator's (Roby / the super-agent's) call, on its own channel, respecting
+  quiet-hours.
+- **Not the orchestrator?** If the message needs the owner's attention or a
+  decision, relay it up: `apx send <you> roby "…" --deliver`. Roby decides how
+  and when to tell the owner. Otherwise just do your part and reply on a2a.
+  - **Tag the urgency** so Roby knows how fast to surface it:
+    `--severity blocker` is a critical alert — Roby pings the owner **in the act**,
+    crossing quiet-hours and the interruption budget (use only for what truly
+    can't wait); `--severity status` / `--severity fyi` is a normal notice that
+    rides the end-of-day digest and never interrupts. Untagged = normal. The
+    `send` result reports `owner_notified` when a `blocker` reached the phone.
+- **Secretary profile active?** Anything promised to / owed to / needing action
+  from the owner must be CAPTURED as a commitment (`record_commitment` /
+  `apx commitment`, with a due date) so it resurfaces at the right time — a lone
+  a2a message is not a reminder, and quiet-hours can swallow a one-off ping.
+
 ## APC_RESULT contract
 
 To capture a structured value from the external runtime, instruct it via the prompt to print on its last line:

package/src/core/runtime-skills/apx-sessions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: apx-sessions
-description: "Cross-engine session ops (apx, claude, codex, antigravity): find by title, list, get transcript, summarize, ask, resume, continue. Triggers: 'apx session find/ask/summary/resume/get', 'find/resume/summarize session', 'get session transcript', 'continue session in apx'. Not for `apx run` orchestration (use apx skill)."
+description: "Cross-engine session ops (apx, claude, codex, opencode, antigravity): find by title, list, get transcript, summarize, ask, resume, continue. Triggers: 'apx session find/ask/summary/resume/get', 'find/resume/summarize session', 'get session transcript', 'continue session in apx'. Not for `apx run` orchestration (use apx skill)."
 ---
 
 # APX Sessions — cross-engine resume, summary, continuation
@@ -14,6 +14,7 @@ Storage locations APX scans:
 | apx       | `~/.apx/projects/<apx_id>/agents/<slug>/sessions/*.md`    |
 | claude    | `~/.claude/projects/<encoded-cwd>/<id>.jsonl`             |
 | codex     | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`            |
+| opencode  | `~/.local/share/opencode` (also `~/.config/opencode`) — listed via the `opencode` CLI (`session list` / `export`) |
 | antigravity | detected only — listing not implemented yet              |
 
 Uninstalled engines are skipped silently. Detected-but-empty engines print `(sin nada)`.
@@ -77,7 +78,7 @@ Limits of `ask`: binary noise (base64 images) is stripped before chunking. Cover
 ```bash
 apx sessions list                                       # all engines, all projects
 apx sessions list --dir /path/to/repo                   # all engines, one dir (no registration needed)
-apx sessions list --project iacrmar                     # all engines, registered project
+apx sessions list --project acme                     # all engines, registered project
 apx sessions list --engine claude                       # one engine, all projects
 apx sessions list --engine codex --dir /path --limit 10 # one engine, one dir
 ```
@@ -88,7 +89,7 @@ Per engine: `DATE | SESSION ID | TITLE` newest first, plus the native-CLI resume
 
 ## Resuming by id (`apx session resume <id>`)
 
-1. Searches every engine (apx → claude → codex).
+1. Searches every engine (apx → claude → codex → opencode).
 2. **One match** → prints metadata (engine, path, cwd, title).
 3. **Zero matches** → non-zero exit with `session "<id>" not found in any detected engine`.
 4. **Multiple matches** → prints all, exit 2, asks for `--engine <id>`.
@@ -97,7 +98,7 @@ Flags:
 
 | Flag | Effect |
 |------|--------|
-| `--engine <apx\|claude\|codex>` | Skip auto-detection. |
+| `--engine <apx\|claude\|codex\|opencode>` | Skip auto-detection. |
 | `--tail N[k\|m]` | Print last N bytes (e.g. `--tail 32k`). No daemon. |
 | `--full` / `--body` | Dump entire transcript. No daemon. |
 | `--summary` | Tail → super-agent → 4-bullet summary. **Daemon + `super_agent.enabled`.** |
@@ -161,7 +162,7 @@ If the daemon is down, `apx` auto-starts it when needed.
 
 ---
 
-## Native APX session commands (legacy, still useful)
+## Native APX session commands
 
 Manage APX-native sessions (`.md` files in `~/.apx/projects/.../sessions/`). They do **not** see Claude/Codex sessions.
 
@@ -185,7 +186,7 @@ $ apx session resume abc123
 ⚠️  session id "abc123" exists in multiple engines:
   - claude  /Users/.../-Volumes-work-repo/abc123.jsonl  (cwd: /Volumes/work/repo)
   - codex   /Users/.../sessions/2026/05/27/rollout-...-abc123.jsonl  (cwd: /Volumes/work/repo)
-→ re-run with --engine <id> to pick one (apx | claude | codex)
+→ re-run with --engine <id> to pick one (apx | claude | codex | opencode)
 ```
 
 Pick one with `--engine claude` or `--engine codex`.

package/src/core/runtime-skills/apx-skill-builder/SKILL.md

@@ -17,11 +17,13 @@ A **skill** is a Markdown file the super-agent loads on demand. Inspired by Anth
 
 Scanned in priority order:
 
-1. `<repo>/.apc/skills/<slug>/SKILL.md` — project-scoped.
+1. `<repo>/.apc/skills/<slug>/SKILL.md` (or flat `<slug>.md`) — project-scoped.
 2. `~/.apx/skills/<slug>/SKILL.md` — user-global.
-3. `<repo>/skills/<slug>/SKILL.md` in the APX source — bundled.
+3. `<packageRoot>/src/core/runtime-skills/<slug>/SKILL.md` — the runtime-internal set that ships with APX (the built-in `apx-*`, `apc-context`, `claude-code`, …). This is where a new super-agent skill goes.
 
-Layouts: `<slug>/SKILL.md` (dir-style, preferred — supports `references/`, `assets/`) or `<slug>.md` (flat, fine for short).
+> ⚠️ `<repo>/skills/` is **NOT** in the super-agent's load chain (see `src/core/agent/skills/loader.js:23`). That folder is the slim engine-side set replicated to external CLIs/IDEs (`~/.claude/skills/`, `~/.codex/skills/`). A skill authored there will never load for the super-agent — put it under `src/core/runtime-skills/`.
+
+Layouts: `<slug>/SKILL.md` (dir-style, preferred — supports `references/`, `assets/`) or `<slug>.md` (flat, fine for short — project scope only).
 
 ## Frontmatter
 
@@ -40,7 +42,7 @@ scope: public   # public (synced globally) | internal (repo/dev-only) | optional
 
 ## Body style
 
-Opinionated, concrete, anti-example-driven. Read a sibling `skills/apx-*` before writing yours. Shape:
+Opinionated, concrete, anti-example-driven. Read a sibling `src/core/runtime-skills/apx-*` before writing yours. Shape:
 
 1. **One-paragraph "what this is"** — no preamble.
 2. **Concrete CLI calls** — most common first.
@@ -69,13 +71,13 @@ apx skills status        # what's installed vs available
 
 ```bash
 # 1. Pick scope:
-#    .apc/skills/<slug>/SKILL.md   (project)
-#    ~/.apx/skills/<slug>/SKILL.md (user-global)
-#    skills/<slug>/SKILL.md        (bundled, in repo)
+#    .apc/skills/<slug>/SKILL.md                     (project)
+#    ~/.apx/skills/<slug>/SKILL.md                   (user-global)
+#    src/core/runtime-skills/<slug>/SKILL.md         (runtime-internal, ships with APX)
 
 # 2. Write
-mkdir -p skills/my-thing
-$EDITOR skills/my-thing/SKILL.md
+mkdir -p src/core/runtime-skills/my-thing
+$EDITOR src/core/runtime-skills/my-thing/SKILL.md
 
 # 3. Verify (daemon picks up on next listSkills() — no restart)
 apx skills list | grep my-thing
@@ -98,13 +100,13 @@ name: vague-stuff
 # Teach the decision tree ("shared vs runtime", "what to do if it fails").
 
 # DON'T leave TODOs in production skills. Delete incomplete sections;
-# move them to spec/backlog/.
+# move them to spec/active/backlog/ (local-only).
 ```
 
 ## Optional scaffolding
 
 ```
-skills/my-thing/
+src/core/runtime-skills/my-thing/
 ├── SKILL.md           ← always
 ├── references/        ← markdown the skill cites
 ├── assets/            ← images, schemas, sample inputs
@@ -115,11 +117,11 @@ Only `SKILL.md` is auto-loaded. Reference others by relative path from the body
 
 ## Existing skills — mimic the style
 
-`skills/apx-routine`, `apx-mcp`, `apx-task`, `apx-telegram`, `apx-runtime`, `apx-sessions`, `apx-voice`, `apx-agent`, `apx-project`. Pick the closest topic, copy the structure.
+`src/core/runtime-skills/apx-routine`, `apx-mcp`, `apx-integrations`, `apx-task`, `apx-telegram`, `apx-runtime`, `apx-sessions`, `apx-voice`, `apx-agent`, `apx-project`. Pick the closest topic, copy the structure.
 
 ## Maintainer contract
 
-`AGENTS.md` rule 6 (regenerated by `apx agent add/import`) requires skills to move in lockstep with feature changes. Update or add the skill in the same PR as the behavior change — especially `skills/apx-*`.
+The dev guide `AGENTS.md` (repo root) rule 6 requires skills to move in lockstep with feature changes. Update or add the skill in the same PR as the behavior change — especially `src/core/runtime-skills/apx-*`.
 
 ## Don't
 

package/src/core/runtime-skills/apx-task/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: apx-task
-description: Per-project TODO list. Event-sourced, project-scoped, addressable by short id prefix. Load when user wants to note, remind, list, or complete a task. Triggers: 'add a task', 'remind me to…', 'what's pending', 'mark as done', 'open tasks'.
+description: Per-project TODO list with subtasks, comments and a board. Event-sourced, project-scoped, addressable by short id prefix. Load when user wants to note, remind, list, complete, split or comment on a task. Triggers: 'add a task', 'remind me to…', 'what's pending', 'mark as done', 'open tasks', 'split this task', 'subtask', 'comment on the task', 'move it to QA'.
 ---
 
 # apx-task
@@ -11,30 +11,33 @@ A `task` is a per-project TODO. Append-only JSONL event log per month at `~/.apx
 
 ```bash
 # Add
-apx task add "Review the auth bug" --project iacrmar
-apx task add "Call the client" --project iacrmar --due 2026-05-30 --tag urgent
-apx task add "Demo for tester X" --project iacrmar --agent reviewer --tag demo --tag external --source cli
+apx task add "Review the auth bug" --project acme
+apx task add "Llamar al contador" --project casa --description "Antes del viernes, por el monotributo"
+apx task add "Rotar las claves" --project acme --body "Rotate every API key in .env and open a PR" --agent ops
+apx task add "Call the client" --project acme --due 2026-05-30 --tag urgent
+apx task add "Demo for tester X" --project acme --agent reviewer --tag demo --tag external --source cli
 
 # List (defaults to open)
-apx task list --project iacrmar
+apx task list --project acme
 apx task list --all                          # every registered project, each row labelled
 apx task list --all --status blocked         # what is stuck, everywhere
 apx task list --all --updated-since 2026-08-01T00:00:00Z   # what moved
-apx task list --project iacrmar --status in_review
-apx task list --project iacrmar --state all
-apx task list --project iacrmar --state done
-apx task list --project iacrmar --tag urgent
-apx task list --project iacrmar --due-before 2026-06-01
-apx task list --project iacrmar --limit 5
+apx task list --project acme --status in_review
+apx task list --project acme --state all
+apx task list --project acme --state done
+apx task list --project acme --tag urgent
+apx task list --project acme --due-before 2026-06-01
+apx task list --project acme --limit 5
 
 # Inspect / mutate
-apx task show t_abc123 --project iacrmar
-apx task show abc       --project iacrmar    # prefix match (≥3 chars, unique)
-apx task done    t_abc123 --project iacrmar --by manuel
-apx task drop    t_abc123 --project iacrmar               # archived (not "done")
-apx task reopen  t_abc123 --project iacrmar
-apx task patch   t_abc123 --project iacrmar --title "New title" --due 2026-06-10
-apx task patch   t_abc123 --project iacrmar --tag bug --tag blocker   # replaces tags
+apx task show t_abc123 --project acme
+apx task show abc       --project acme    # prefix match (≥3 chars, unique)
+apx task done    t_abc123 --project acme --by manuel
+apx task drop    t_abc123 --project acme               # archived (not "done")
+apx task reopen  t_abc123 --project acme
+apx task patch   t_abc123 --project acme --title "New title" --due 2026-06-10
+apx task patch   t_abc123 --project acme --description "Lo que tengo que hacer yo"
+apx task patch   t_abc123 --project acme --tag bug --tag blocker   # replaces tags
 ```
 
 ## ID format
@@ -46,23 +49,71 @@ apx task patch   t_abc123 --project iacrmar --tag bug --tag blocker   # replaces
 | Field | When | Notes |
 |---|---|---|
 | `title` | always | One imperative line. Required. |
-| `body` | optional | Longer notes. Markdown OK. |
+| `description` | optional | **What the OWNER has to do**, in their words. Markdown OK. This is what the panel, the phone and `apx task show` display. Fill it for anything a person will do. |
+| `body` | optional | **The prompt an AGENT receives** if it runs the task. Only for tasks meant to be executed by an agent — leave it empty for a plain to-do. |
 | `tags` | optional | Free-form. Used by `--tag` filter. |
-| `due` | optional | ISO `YYYY-MM-DD`. Supports `--due-before`. |
+| `due` | optional | ISO `YYYY-MM-DD`. Filter with `--due-before` / `--due-after`. |
 | `agent` | optional | Slug of responsible agent. Used by `--agent` filter. |
 | `source` | auto/optional | Origin (cli, telegram, super-agent). |
-| `state` | derived | `open` after create, `done`/`dropped` after ops. |
+| `state` | derived | Storage lifecycle: `open` after create, `done`/`dropped` after ops. |
+| `status` | sub-status | Which BOARD COLUMN an **open** task sits in. Ships as `pending` (default) \| `running` \| `in_review` \| `blocked`, but the column catalog is configurable — call `GET /api/projects/:pid/tasks/columns` for what THIS project actually has. Orthogonal to `state`. Set via `POST …/tasks/:id/status` (the CLI `patch` does not set it). |
+| `parent` | optional | Id of a parent task. **A subtask is a task with a parent** — same store, same verbs, so it can be assigned, moved and closed on its own. |
+| `comments` | derived | The task's thread, oldest first. Present on `show`/`GET one`; list rows carry `comment_count` instead. |
+
+## Subtasks — splitting a task that is really several
+
+One row that bundles five requirements cannot be handed out, moved to QA, or
+ticked off in pieces. Split it: keep the parent as the epic and add a subtask
+per real unit of work.
+
+```bash
+apx task list --project acme --parent t_epic123   # its children
+apx task list --project acme --parent ""          # only top-level tasks
+```
+
+With the tool: `create_task({ project, title, parent: "t_epic123" })`.
+
+## Comments, and handing a task to an agent
+
+```
+POST /api/projects/:pid/tasks/:id/comments   { text }
+```
+
+**An @mention in a comment summons that agent.** It runs a REAL turn with its
+own tools against the task, and its reply is posted back as another comment —
+so "@qa probá el flujo de login" is a QA run, not a note. Agent→agent handovers
+(`@dev` inside QA's reply) cascade, are mirrored onto the a2a ledger, and stop
+at a ceiling of 4 replies per comment so a mention loop cannot run away.
+
+The `comment_task` tool writes a comment but **summons nobody** — that is
+deliberate: only the owner's comment, and the cascade already running under its
+ceiling, can start a turn. To hand work over, name the agent in your reply.
+
+## Board columns
+
+One catalog for every project (`config.tasks.columns`), and each project shows
+an ordered subset (`.apc/config.json` → `tasks.columns`). `done` is always the
+last column and is not in the catalog — closing a task is `POST …/done`, not a
+status. A column may carry `on_enter: { agent, instruction }`: a task landing
+there is handed to that agent through the same comment path as an @mention.
+
+```bash
+GET  /api/tasks/columns                  # the global catalog
+GET  /api/projects/:pid/tasks/columns    # what this project shows, + the catalog
+```
 
 ## Super-agent tools
 
-The super-agent has `create_task` and `list_tasks`. "Note that we need to close the auth bug in iacrmar tomorrow" → model calls:
+The super-agent has `create_task`, `list_tasks`, **`complete_task`** (done | drop | reopen | status) and **`comment_task`**. Add, list, and close all happen with tools — no shelling out to `apx task done`. "Note that we need to close the auth bug in acme tomorrow" → model calls:
 
 ```json
 { "name": "create_task",
-  "arguments": { "project": "iacrmar", "title": "Close the auth bug", "due": "<tomorrow>", "tags": ["bug"] } }
+  "arguments": { "project": "acme", "title": "Close the auth bug", "description": "The 401 on refresh — reproduce it first", "due": "<tomorrow>", "tags": ["bug"] } }
 ```
 
-"What's pending in iacrmar?" → `list_tasks({ project: "iacrmar" })`. If user doesn't say which project, `list_projects` first and ask — never assume. If the channel has pinned project context (Telegram), use that.
+**`description` vs `body`.** `description` is for the person; `body` is the prompt an agent receives. Most tasks the owner dictates are the first kind — write the description and leave `body` empty. Putting a prompt where the description belongs is what turns a to-do list into a queue of jobs its owner cannot read.
+
+"What's pending in acme?" → `list_tasks({ project: "acme" })`. If user doesn't say which project, `list_projects` first and ask — never assume. If the channel has pinned project context (Telegram), use that.
 
 ## Anti-examples
 
@@ -79,14 +130,16 @@ apx task drop t_abc            # "no longer needed; archive without completion"
 ## Endpoint surface
 
 ```
-GET    /api/projects/:pid/tasks                  ?state=open|done|dropped|all&tag=X&agent=Y&due_before=ISO&limit=N
+GET    /api/tasks                                cross-project; same filters, plus ?offset
+GET    /api/projects/:pid/tasks                  ?state=open|done|dropped|all&status=pending|running|in_review|blocked&tag=X&agent=Y&due_before=ISO&due_after=ISO&updated_since=ISO&limit=N
 POST   /api/projects/:pid/tasks                  { title, body?, tags?, due?, agent?, source?, meta? }
 GET    /api/projects/:pid/tasks/:id
 PATCH  /api/projects/:pid/tasks/:id              { patch: {...} }
 POST   /api/projects/:pid/tasks/:id/done         { by? }
 POST   /api/projects/:pid/tasks/:id/drop         { by? }
 POST   /api/projects/:pid/tasks/:id/reopen
-GET    /api/projects/:pid/tasks-summary          → { open, done, dropped, overdue, total }
+POST   /api/projects/:pid/tasks/:id/status       { status: pending|running|in_review|blocked }
+GET    /api/projects/:pid/tasks-summary          → { open, done, dropped, overdue, total, status:{…} }
 ```
 
 ## Don't