@agentprojectcontext/apx 1.14.0 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"
@@ -25,6 +25,7 @@
     "smoke": "node src/daemon/smoke.js",
     "test": "node --test --test-reporter=spec tests/*.test.js",
     "upgrade": "npm install && npm install -g .",
+    "prepack": "node scripts/sync-apc-skill.js",
     "postinstall": "node src/cli/postinstall.js"
   },
   "dependencies": {

package/skills/apc-context/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: apc-context
 description: "ALWAYS activate when the project has a .apc/ directory or AGENTS.md file. Do not wait to be asked. Read .apc/ before making any assumption about agents, memory, or project structure. Activate on: .apc/, AGENTS.md, 'which agents', 'list agents', 'agent context', 'who are the agents', any question about agents or memory in this project. IMPORTANT: if .apc/migrate.md exists, open the conversation with a migration offer before answering anything else. If the user declines, delete .apc/migrate.md immediately so it is not shown again."
-homepage: https://github.com/agentprojectcontext/apx
+homepage: https://github.com/agentprojectcontext/agentprojectcontext
 ---
 
 # Agent Project Context
@@ -20,27 +20,47 @@ Before doing anything else, check if `.apc/migrate.md` exists:
 cat .apc/migrate.md 2>/dev/null
 ```
 
-If it exists, offer to migrate before answering anything else. Read detected files, separate durable
-project context from runtime/private state, and migrate only what belongs in APC.
+If it exists, open with this offer before answering anything else:
+
+> I see this project was initialized with Agent Project Context (APC).
+>
+> I found context files that may need migration:
+> [list files from .apc/migrate.md]
+>
+> I can read them, separate durable project context from runtime/private state, and migrate only
+> what belongs in APC.
+>
+> Want me to start?
 
 If the user says no or later, delete `.apc/migrate.md` so the offer is not repeated.
 
 ## Migration rule: think, do not copy
 
+Read detected files first. Also read `AGENTS.md` if it exists.
+
 Classify content:
 
 | Content | Action |
 |---|---|
-| Agent definitions: role, model, skills, description | Put in `.apc/agents/<slug>.md` and/or `AGENTS.md` |
+| Agent definitions: name, model, description | Put in `.apc/agents/<name>.md` and/or `AGENTS.md` |
 | Shared project rules, stack notes, commands, testing policy | Keep in `AGENTS.md` |
 | Reusable instruction blocks | Move to `.apc/skills/<name>.md` |
-| Durable safe facts useful to all contributors | Add to `.apc/agents/<slug>/memory.md` only after curation |
+| Durable safe facts useful to all contributors | Add to `.apc/agents/<name>/memory.md` only after curation |
 | MCP expectations without secrets | Add to `.apc/mcps.json` |
 | Raw sessions, transcripts, conversations, messages, tool logs | Do not move into `.apc/`; leave with source runtime |
 | Secrets, tokens, credentials, private headers | Do not store in repository |
 | IDE UI settings or personal aliases | Leave in IDE/user config |
 | Instructions to store sessions under `.apc/` | Drop as obsolete |
 
+After migration:
+
+1. Update `AGENTS.md` as the root project contract.
+2. Create or update `.apc/agents/`, `.apc/skills/`, `.apc/mcps.json` as needed.
+3. Do not create `.apc/**/sessions`, `.apc/messages`, or `.apc/conversations`.
+4. Delete obsolete source files only when their useful project context was migrated or intentionally dropped.
+5. Delete `.apc/migrate.md`.
+6. Summarize what moved, what stayed local, and what was dropped.
+
 ## APC structure
 
 ```text
@@ -48,8 +68,8 @@ AGENTS.md                        ← root project contract
 .apc/
   project.json                   ← project metadata
   .gitignore                     ← safety guard
-  agents/<slug>.md               ← agent definition
-  agents/<slug>/memory.md        ← optional curated project memory
+  agents/<name>.md               ← agent definition
+  agents/<name>/memory.md        ← optional curated project memory
   skills/<name>.md               ← reusable project instructions
   mcps.json                      ← MCP hints without secrets
 ```
@@ -57,7 +77,7 @@ AGENTS.md                        ← root project contract
 Do not store:
 
 ```text
-.apc/agents/<slug>/sessions/
+.apc/agents/<name>/sessions/
 .apc/sessions/
 .apc/conversations/
 .apc/messages/
@@ -68,16 +88,41 @@ Do not store:
 .apc/secrets/
 ```
 
+## Visibility rules
+
+| Data | Visibility | Commit? |
+|---|---|---|
+| Agent definitions, skills, project rules | `stable` / `project` | Yes |
+| Curated safe `memory.md` | `project` | Yes, if team-safe |
+| MCP hints without secrets | `project` | Yes |
+| Sessions, conversations, messages | `local` | No; runtime-owned |
+| Secrets, tokens, `*.secret.json`, `*.env` | `private` | Never |
+| Caches, temp files, databases | `ephemeral` | No |
+
 ## Operating rules
 
 1. Read `AGENTS.md` and relevant `.apc/` files before assuming project context.
-2. Read agent definitions from `.apc/agents/<slug>.md` when present.
-3. Read curated project memory from `.apc/agents/<slug>/memory.md` when present.
+2. Read agent definitions from `.apc/agents/<name>.md` when present.
+3. Read curated project memory from `.apc/agents/<name>/memory.md` when present.
 4. Write only durable, safe, curated facts to APC memory.
 5. Never write raw sessions, transcripts, messages, conversations, or tool logs into `.apc/`.
 6. Keep secrets out of APC and out of git.
 7. Treat `.apc/mcps.json` as MCP configuration hints, not as an MCP implementation.
 
+## Normalization
+
+If agent formats are broken or use legacy fields (role, skills in YAML), offer to normalize:
+
+```yaml
+---
+name: agent-name
+model: inherit
+description: Semantic activation trigger
+---
+```
+
+Identify and fix inconsistencies in `model` (use technical IDs or `inherit`) and ensure `description` is present for semantic activation.
+
 ## Sessions
 
 Sessions belong to the runtime that created them.
@@ -88,23 +133,28 @@ Examples:
 Codex runtime storage
 Claude Code runtime storage
 OpenCode runtime storage
-~/.apx/projects/<project-id>/agents/<slug>/sessions/
+~/.apx/projects/<project-id>/agents/<name>/sessions/
 ```
 
 At task end, provide the user a concise result. If project memory should be updated, write a short
-sanitized fact to `.apc/agents/<slug>/memory.md` only when useful and safe.
+sanitized fact to `.apc/agents/<name>/memory.md` only when useful and safe.
 
 ## APX
 
-APX can provide a local daemon, MCP management, Telegram bridge, routines, and runtime dispatch
-across Codex, Claude Code, OpenCode, Aider, Cursor Agent, Gemini CLI, Qwen Code, or direct LLM
-engines. Those are APX runtime features, not APC portable-core requirements.
+Read `.apc/project.json` if present. It may contain an `apx` field:
 
-The APX super-agent uses `~/.apx/projects/default` for system-level work when no project is named.
-APX routines can run heartbeat, shell, Telegram, project agent, or super-agent tasks on a schedule.
+- `"installed"`: APX is available; use `apx` commands when useful.
+- `"declined"`: user chose not to install; do not suggest or run APX.
+- missing or `null`: unknown; do not assume APX is available.
 
-APX runtime state belongs outside the repository:
+If APX is installed, it may manage runtime state outside the repository:
 
 ```text
 ~/.apx/projects/<project-id>/
 ```
+
+APX can provide a local daemon, MCP management, Telegram bridge, routines, and runtime dispatch
+across Codex, Claude Code, OpenCode, Aider, or direct LLM engines. Those are APX runtime features,
+not APC portable-core requirements.
+
+Never use APX to write secrets or raw sessions into `.apc/`.

package/skills/apx/SKILL.md

@@ -1,29 +1,34 @@
 ---
 name: apx
-description: "APX CLI skill. Activate ONLY when the user asks about running agents, coordinating between agents, or explicitly uses apx commands. Provides: apx run, apx exec, apx memory, apx mcp, apx session, apx messages tail. Do NOT activate just because .apc/ exists — project context is handled by the apc-context skill. Activate on: 'apx run', 'apx exec', 'run an agent', 'coordinate agents', 'multi-agent', 'apx memory', 'apx mcp', 'daemon'."
+description: "APX CLI skill. Activate when: user asks to run or coordinate agents, use MCP tools from .apc/mcps.json, install agents from a team workspace, or explicitly mentions apx commands. Do NOT activate just because .apc/ exists — that is handled by the apc-context skill. Activate on: 'apx run', 'apx exec', 'run an agent', 'coordinate agents', 'MCP not working', 'install agent', 'team agents', 'apx memory', 'daemon'."
 homepage: https://github.com/agentprojectcontext/apx
 ---
 
 # APX — Agent Project Context Runtime
 
-This project uses **APX**. The daemon runs on `127.0.0.1:7430` and auto-starts on first `apx` call.
-Your current session, project, and agent are already injected above this block — refer to them.
+The daemon runs on `127.0.0.1:7430` and auto-starts on first `apx` call.
 
-APX runtime state belongs outside `.apc/`, under `~/.apx/projects/<project-id>/`.
+APX reads APC project context from `.apc/`, but APX runtime state belongs outside the repository
+under `~/.apx/projects/<project-id>/`.
+
+The APX super-agent has an always-available default workspace at `~/.apx/projects/default`.
+When no project is named, system-level work belongs there.
 
 ---
 
-## Discover the project
+## Coordinate with other agents
 
-```bash
-apx agent list                          # agents in AGENTS.md + their roles/models
-apx mcp list                            # MCP servers available to this project
-```
+**First: can you spawn a subagent natively in this IDE?**
 
-## Coordinate with other agents
+If yes — do that. No APX needed. Claude Code, Cursor, and other IDEs can spawn subagents directly using your current context.
+
+Use `apx run` only when:
+- The user explicitly asks to run the agent in a specific external runtime ("run this in Codex", "run the QA agent outside this session")
+- You need to run an agent in a runtime different from the one you're in
+- You're orchestrating from outside any IDE (e.g. a script, Telegram bot, CI)
 
 ```bash
-# Full external session (best for complex, multi-step tasks)
+# Run agent in an external runtime — full isolated session
 apx run <slug> --runtime claude-code "<prompt>"
 apx run <slug> --runtime codex        "<prompt>"
 apx run <slug> --runtime opencode     "<prompt>"
@@ -32,54 +37,105 @@ apx run <slug> --runtime cursor-agent "<prompt>"
 apx run <slug> --runtime gemini-cli   "<prompt>"
 apx run <slug> --runtime qwen-code    "<prompt>"
 
-# Quick one-shot LLM call (requires engine API key in ~/.apx/config.json)
+# Example: run the qa agent in codex with a specific task
+apx run qa --runtime codex "run the full test suite and report failures"
+```
+
+The output is the agent's full stdout. If it printed `APC_RESULT: <value>`, that value is captured as structured output.
+
+```bash
+# Quick one-shot LLM call (no external CLI needed, uses ~/.apx/config.json engine key)
 apx exec <slug> "<prompt>"
 ```
 
-The output of `apx run` / `apx exec` is the agent's full stdout.
-If the agent printed `APC_RESULT: <value>`, that value is also captured as structured output.
+## Command accuracy
+
+Do not invent APX subcommands. Before telling another runtime to call APX, verify the exact CLI
+form with `apx --help` or `apx <command> --help`.
+
+Known Telegram form:
+
+```bash
+apx telegram status
+apx telegram send "message"
+apx telegram send "message" --chat 123456
+```
+
+Do not use guessed aliases such as `apx send-telegram` or `apx telegram "message"` unless current
+`apx --help` shows that exact form.
 
-## Memory — durable, safe facts
+## MCP tools
+
+MCPs declared in `.apc/mcps.json` are proxied through the APX daemon. Use `apx mcp` only for MCPs registered there — not for MCPs that are already running locally in your IDE session.
+
+```bash
+apx mcp list                            # MCPs registered in .apc/mcps.json
+apx mcp tools <server>                  # tools a server exposes
+apx mcp run   <server> <tool> '<json>'  # call a tool
+
+# Example:
+apx mcp tools filesystem
+apx mcp run filesystem read_file '{"path": "README.md"}'
+```
+
+## Memory
+
+Write memory only for durable, safe project facts. Do not store raw transcripts or secrets.
 
 ```bash
 apx memory <slug>                       # read agent's memory.md
-apx memory <slug> --append "<fact>"     # append a durable note (non-destructive)
+apx memory <slug> --append "<fact>"     # append a durable note
 apx memory <slug> --replace < file.md  # replace entire memory from stdin
 ```
 
-Write to memory only when you discover safe project context the agent should know on future runs.
+## Sessions
+
+Sessions are APX runtime state. They do not belong in `.apc/`.
+
+```bash
+apx session new <slug> --title "What you did"   # create APX local session file
+apx session list <slug>                          # list sessions
+apx session check                                # exits 1 if session already active
+```
 
 ## Observe activity
 
 ```bash
-apx messages tail                       # last 50 messages, all channels
-apx messages tail --channel runtime     # only agent invocations (in/out)
-apx messages tail --channel telegram    # Telegram conversation history
+apx messages tail                               # last 50 messages, all channels
+apx messages chat --channel telegram -n 20      # chat view with user/agent/system type
+apx messages tail --channel runtime             # only agent invocations
 apx messages tail --agent <slug> -n 20
-apx session list  <slug>                # sessions for a specific agent
 ```
 
-## MCP tools
+Message rows expose `type` (`user`, `agent`, `tool`, `system`) and `actor_id`; use `messages chat`
+when you need a readable transcript.
+
+## APX tool permissions
 
 ```bash
-apx mcp list                            # registered MCP servers
-apx mcp tools <server>                  # list tools a server exposes
-apx mcp run   <server> <tool> '<json>'  # call a tool directly
+apx permission show
+apx permission set automatico   # total | automatico | permiso
 ```
 
-## Anti-collision guard
+`automatico` runs read/list/safe shell checks directly and asks before destructive shell, MCP,
+runtime, outbound, config, or filesystem mutation actions.
+
+## Routines
 
-Before starting a long task, prevent duplicate runs:
 ```bash
-apx session check    # exits 1 if a session is already active for this agent
+apx routine list
+apx routine get <name>
+apx routine history <name>
+apx routine add clima --kind super_agent --schedule every:5m \
+  --permission-mode total \
+  --spec '{"prompt":"Check weather and send Telegram update."}'
 ```
 
-## APC_RESULT — how to signal your return value
+Routine kinds: `heartbeat`, `exec_agent`, `super_agent`, `telegram`, `shell`.
+
+## APC_RESULT
 
-Print this on the last meaningful line of your output:
+Print on the last meaningful line of your output so the invoker captures it:
 ```
 APC_RESULT: <one-line summary or value>
 ```
-The invoker (`apx run`, super-agent, Telegram bot) captures it as structured output.
-Keep it factual and short. It becomes the session result stored in APX local runtime state, not
-inside `.apc/`.