edercnj/x-internal-load-agent-context

Output Contract & Context Management

Emit a single-line JSON envelope on success. On error, emit a JSON object with status: "error" and message. No greetings or explanations.

Skill: x-internal-load-agent-context

🔒 INTERNAL SKILL — Called only by orchestrating skills. Not user-invocable.

Resolves an agent file by name or path, reads it, and returns its persona, core knowledge directives, tools, and rules as a structured JSON envelope. This skill is the canonical implementation of the agent binding mechanism.

Callers must inject the returned context into their execution before proceeding with domain logic.

Triggers

Only called by other skills via Skill(skill: "x-internal-load-agent-context", args: "--agent <name>").

Parameters

| Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | --agent | Yes | — | Agent name (e.g. devops-engineer) or relative path (e.g. .team-development/src/agents/devops-engineer.md) | | --team | No | — | Team directory to search first (e.g. .team-development). Overrides default resolution order for that team's agents. |

Phase 1 — Resolve Agent File Path

Input: --agent value.

Action:

1. If --agent value contains / or \, treat as a relative path from repo root. Verify the file exists; if not, halt with error.
2. Otherwise, resolve by name in this order: a. src/agents/<name>.md b. .team-development/src/agents/<name>.md c. If --team was provided: <team>/src/agents/<name>.md (checked before step b)
3. First match wins. If no file is found in any location, halt with:

   {"status": "error", "message": "Agent '<name>' not found. Searched: src/agents/, .team-development/src/agents/"}
   

Output: Resolved absolute or relative path to the agent file.

Phase 2 — Parse Agent File

Input: Resolved agent file path.

Action:

1. Read the agent file.
2. Extract from frontmatter YAML:
   • name → agent_name
   • description → agent_description
   • tools → tools (array)
   • model → model
3. Extract from body (Markdown sections):
   • Persona block: text under ## Persona section (or any H2 whose name contains "Persona"). If absent, use the description frontmatter value.
   • Core Knowledge: all Read <path> directives under ## Core Knowledge section. Return as array of strings.
   • Rules: all bullet/numbered items under ## Rules section (last H2 named "Rules"). Return as array of strings.
   • Full body: the raw Markdown content of the agent file (excluding frontmatter), for callers that need to inject the complete persona.

Output: Structured parsed data.

On error: If file is unreadable, return {"status": "error", "message": "Cannot read agent file at <path>: <os-error>"}.

Phase 3 — Emit Envelope

Input: Parsed data from Phase 2.

Action: Emit the following JSON envelope to stdout (single line, no trailing newline):

{
  "status": "ok",
  "agent_name": "<name>",
  "agent_description": "<description>",
  "model": "<model>",
  "tools": ["Read", "Bash", "Grep"],
  "persona": "<persona text>",
  "core_knowledge": [
    "Read src/knowledge/shared/governance-baselines/coding-standards-rule/knowledge.md",
    "Read src/patterns/backend/software-architecture/hexagonal/patterns.md"
  ],
  "rules": [
    "REQUEST CHANGES if container runs as root",
    "NO-GO if ANY item in Architecture (1-8) fails"
  ],
  "full_body": "<complete agent markdown body>",
  "source_path": "src/agents/devops-engineer.md"
}

Caller Integration Pattern

Orchestrating skills should follow this pattern in their Phase 0:

## Phase 0.1 — Load Agent Context (when --agent provided or agent: frontmatter set)

**Input:** `--agent` value or `agent:` frontmatter field.

**Action:**
Skill(skill: "x-internal-load-agent-context", args: "--agent <agent_name>")

**Output:** `agent_context` envelope.

**Inject:** Adopt the `agent_context.persona` as the active persona for the remainder of this skill's execution. Follow `agent_context.rules` as additional constraints. Read all paths listed in `agent_context.core_knowledge` before proceeding.

**On error:** If `agent_context.status == "error"`, halt and surface `agent_context.message`.

Output

| Field | Type | Description | |-------|------|-------------| | status | "ok" | "error" | Resolution status | | agent_name | String | Agent name from frontmatter | | agent_description | String | Agent description from frontmatter | | model | String | Model declared by the agent | | tools | Array | Tools the agent is allowed to use | | persona | String | Persona text extracted from ## Persona section | | core_knowledge | Array | Read directives from ## Core Knowledge | | rules | Array | Absolute constraints from ## Rules | | full_body | String | Complete agent Markdown body (sans frontmatter) | | source_path | String | Relative path to the resolved agent file |

Rules

• NEVER fall back silently if --agent is provided but the file is not found — always halt with a clear error
• ALWAYS check src/agents/ before .team-development/src/agents/ (unless --team overrides)
• NEVER modify the agent file — this skill is read-only
• ALWAYS emit a single-line JSON envelope; no prose output
• If --agent value is a path (contains / or \), skip name-based resolution entirely

Error Codes

| Code | Condition | |------|-----------| | AGENT_NOT_FOUND | No file matched the name in any search location | | AGENT_FILE_UNREADABLE | File exists but cannot be read (permissions, encoding) | | AGENT_PARSE_FAILED | File is not valid Markdown with YAML frontmatter | | MISSING_ARGUMENT | --agent flag absent from argv |