Implementation Plan: Agent Society Runtime

Make governed multi-agent participation a first-class runtime capability: agent registry (roles/capabilities/boundaries), tool execution via safe transports (MCP/LSP/A2A), human-in-the-loop escalations, and auditable handoffs.

This plan spans documentation artifacts (SKILL.md, AGENTS.md, .github/agents/**) and governance constraints; runtime execution should remain generated or tool-driven (no handwritten runtime logic).

Provenance & Traceability

Architectural Decisions (ADRs)

Product Requirements (PRDs)

Software Design Specifications (SDS)

Note: ADR-017 (MCP-LSP Integration) is now consolidated in SDS-052 (Semantic Tooling & IDE Integration).

Architecture and Design

Design Principles Applied

• Isomorphism: Agent registry is an explicit manifest of artifacts (skills/agents/prompts), not implicit behavior.
• Invariants: Agents cannot self-approve privileged actions (REF-012 §10 INV-GOV-001, SDS-031).
• Idempotency: Tool executions and handoffs have stable IDs and audit trails.

Dependency Justification

• No new dependencies for plan completion; lean on existing .github/** artifacts and ADR-017 patterns.

Expected Filetree

1
2
3
4
5
/
├── .github/agents/**                      # agent definitions
├── .github/skills/**                      # skill definitions
├── docs/specs/shared/adr/017-mcp-lsp-integration-architecture.md
└── docs/specs/shared/sds/031-authority-ownership-boundaries.md

Proposed Cycles

Task Breakdown

Wave 1 (Parallel)

• C1A: Define agent/skill registry structure and routing rules
  • Implements: “What agents exist, what they can do, how they’re invoked”
  • Satisfies: PRD-020 FR-004 (Context-Kit manifest / skills)
  • Files: .github/agents/**, .github/skills/**, docs/specs/shared/sds/045-vibespro-foundation-integration.md
• C1B: Define HITL escalation protocol and audit requirements
  • Implements: Approval request fields, required approvers, audit events
  • Satisfies: SDS-031 and REF-012 §10 governance invariants
  • Files: docs/specs/shared/sds/031-authority-ownership-boundaries.md, docs/specs/.internal/012-invariant-regime.md

Wave 2 (Depends on Wave 1)

• C2A: Restrict agent tool exposure to a safe, minimal subset
  • Implements: Allowed LSP/MCP methods; deny-by-default surfaces (SDS-052)
  • Satisfies: ADR-017 constraints
  • Files: docs/specs/shared/sds/052-semantic-tooling-ide-integration.sds.yaml

Validation & Verification

Spec Validation

• Every privileged agent action references authority boundaries (SDS-031)
• Tool surface is documented and minimal (ADR-017)

Implementation Validation

• All agent actions are traceable (correlation IDs + optional ledger anchoring)
• No agent can approve privileged operations (REF-012 §10 INV-GOV-001)

Open Questions

1. Where is the canonical “agent routing manifest” stored in this repo (SDS-045 mentions ce.manifest.jsonc, but this repo currently uses .github/agents/** and .github/skills/**)? .github/agents/** (current)
2. Which transports are in-scope for MVP: VS Code LSP only, MCP server, A2A, or all? VS Code LSP + MCP + HTTP
3. What is the expected on-disk schema for SKILL.md beyond the system skills in your Codex home? Frontmatter + structured markdown

Risks & Mitigation

Rollback Strategy

1. Disable non-essential agents and retain only “read-only” tooling until governance is stable.

Related Documents

Linked Specifications

Consolidation Note: ADR-017 (MCP-LSP Integration) and SDS-041 (Ultimate LSP Hover) are now consolidated in SDS-052.