ε Skill Registry — Algorithm Extraction

⚠ HERITAGE EXTRACTION — donor AMS ε Skill Registry (Wave 8 quarantine)

This file extracts the donor AMS skill registry from src/skills/ and src/gsd/agent-types.js (deleted R53). The 6-tier taxonomy and the agent-type coupling are donor surface. Phase 0 Colibri ε ships a single tool: skill_list, with no skill_get, no skill_reload, no agent_spawn, no agent_status, no agent typing tied to skills. The canonical Phase 0 ε surface is in ../../concepts/ε-skill-registry.md. Sub-agent dispatch in Phase 0 is via the host client’s Task tool, not via Colibri MCP — δ Model Router and agent spawning are deferred to Phase 1.5 per ADR-005.

Read this file as donor genealogy only.

Algorithmic content extracted from AMS src/skills/ and src/gsd/agent-types.js for Colibri implementation reference.

Skill Tier Taxonomy

Skills are organized into 6 functional tiers:

Tier	Purpose	Example Skills
PM & Orchestration	Coordinate tasks, delegate to sub-agents, manage pipelines	`ams-pm`, `ams-tier1-chains`
Task & Roadmap	CRUD operations on tasks, roadmaps, milestones	task-management, roadmap-progress
GSD & Execution	Run GSD workflow phases, execute implementation work	`ams-executor`, autonomous
Audit & Proof	Build audit trails, generate proofs, manage memory	`ams-observability`, audit-proof
Infrastructure	Server operations, health monitoring, watcher management	mcp-server, observability
Integration	External system connections, sync, notifications	obsidian-integration

Skill Definition Schema

Each skill is a directory under src/skills/<skill-name>/:

skills/<skill-name>/
  SKILL.md           — definition file (required)
  references/        — supporting docs, tool lists, workflow templates (optional)

A SKILL.md defines:

name: <unique-identifier>

triggers:
  - <condition that activates the skill>
  - <tool pattern, task type, or keyword>

required_tools:
  - <mcp tool name>
  - <mcp tool name>

workflow:
  - step: "<description of what to call>"
    tool: "<tool_name>"
    params: { ... }
  - step: "<next step>"
    ...

verification:
  - "<check that skill executed correctly>"
  - "<test assertion>"

Triggers activate skills automatically when matched by the task pipeline or PM. Required tools declare the MCP surface the skill depends on — used for permission checking. Workflow provides an ordered execution script. Verification is used by the VERIFY phase of GSD to confirm correct execution.

Agent Lifecycle States

Defined in src/gsd/agent-types.js. An agent transitions through 6 states:

PENDING → INITIALIZING → READY → BUSY → TERMINATED
    ↓           ↓           ↓       ↓
  FAILED     FAILED      FAILED  FAILED

State	Meaning	Duration
`PENDING`	Agent ID allocated, OS process not yet started	Until parent creates subprocess
`INITIALIZING`	Loading skills, setting up worktree, acquiring tools	Short (seconds)
`READY`	Idle, waiting for task assignment	Until task assigned
`BUSY`	Executing a task	For task duration
`TERMINATED`	Execution complete, resources released	Terminal state
`FAILED`	Error state — any phase can fail	Terminal (may be retried via new agent)

State is persisted to the agents table in SQLite. Transitions are logged to audit_log.

Agent Spawning Algorithm

1. ALLOCATE
   tool: gsd_agent_spawn(task_id, agent_type, pool_config)
   → DB write: INSERT INTO agents (id, type, pool, status='PENDING', task_id)
   → Returns agent_id
   Note: no OS process created yet — this is a planning-level reservation

2. SPAWN
   Parent creates sub-agent subprocess with these injection parameters:
     - agent_id         (from allocation)
     - pool_assignment  (research | implementation | verification | review)
     - worktree_path    (isolated git worktree for code changes)
     - branch_name      (feature/<task-slug>)
     - writeback_contract (what the agent must call before termination)
     - skill_refs       (which skills the agent may invoke)
     - context_snapshot (relevant memory, parent thought chain)
   → Update agents status: PENDING → INITIALIZING

3. INITIALIZE
   Sub-agent loads assigned skills from SKILL.md files
   Sub-agent verifies access to required_tools
   → Update agents status: INITIALIZING → READY

4. EXECUTE
   Sub-agent receives task assignment
   → Update agents status: READY → BUSY
   Sub-agent runs skill workflow (GSD phases: GATHER → ANALYZE → PLAN → APPLY)
   Checkpoints written to DB at phase boundaries

5. WRITEBACK
   Sub-agent calls:
     task_update(task_id, { status, progress, summary })
     thought_record({ task_id, type: "reflection", branch, commit_sha, tests_run, blockers })
   Optional:
     memory_pack(session_id)

6. TERMINATE
   → Update agents status: BUSY → TERMINATED
   Agent ID released from pool
   Parent workflow notified via task pipeline (β)

Writeback Contract

Every agent must produce before termination (convention-level enforcement):

Item	Tool	Minimum fields
Task update	`task_update`	status, progress (0–100), summary
Thought record	`thought_record`	task_id, type=”reflection”, branch, commit_sha, tests_run, blockers
Memory pack	`memory_pack`	session_id (optional but recommended)

Agents that terminate without writeback are flagged as orphaned. An orphan scan runs periodically: it queries agents with status=TERMINATED and no corresponding thought_record, logs warnings, and emits an alert. No automatic rollback or re-execution occurs.

Agent CV (Capability Profile) Structure

Each agent type has a capability profile stored in the agent registry:

{
  "agent_type": "<type-name>",
  "skills": [
    "<skill-name>",
    "<skill-name>"
  ],
  "permissions": {
    "tools": ["<allowed-mcp-tool>", "..."],
    "write_access": true,
    "admin_access": false
  },
  "limits": {
    "max_concurrent_tasks": 1,
    "token_budget": 100000,
    "timeout_ms": 300000
  },
  "history": {
    "success_rate": 0.95,
    "avg_duration_ms": 45000,
    "total_runs": 142
  }
}

The CV is used by the task pipeline (β) during agent allocation:

Skills field checked against task type requirements
Permissions field validated against required_tools in skill definition
Limits field used for pool sizing and queue depth calculation
History field influences CAPACITY_AWARE pool allocation strategy