plan_agent_design_governance

Instructions

Implementation Reference

• scripts/agent-design-governance.js:142-170 (handler)

  Main handler that builds the agent design governance plan. Normalizes inputs, scores tool risk and instruction quality, selects architecture (single_agent/manager/decentralized), identifies blockers, and returns a governance report.

  function buildAgentDesignGovernancePlan(rawOptions = {}) {
    const options = normalizeOptions(rawOptions);
    const toolRisk = scoreToolRisk(options);
    const instructionQuality = scoreInstructions(options);
    const architecture = selectArchitecture(options, toolRisk, instructionQuality);
    const blockers = buildBlockers(options, toolRisk, architecture);
  
    return {
      name: 'thumbgate-agent-design-governance',
      workflow: options.workflow,
      sourcePattern: 'OpenAI practical agent guide: model + tools + instructions, single-agent first, eval-driven multi-agent splits',
      status: blockers.some((blocker) => blocker.severity === 'critical') ? 'blocked' : blockers.length ? 'needs_work' : 'ready',
      recommendation: architecture,
      toolRisk,
      instructionQuality,
      evals: {
        baselinePresent: options.hasBaselineEvals,
        requiredBefore: ['new high-risk tools', 'multi-agent split', 'higher autonomy', 'auto-PR or deploy'],
      },
      blockers,
      nextActions: [
        'Keep the workflow single-agent unless evals show instruction complexity or tool overload.',
        'Write tool descriptions with clear names, parameters, side effects, and approval requirements.',
        'Add examples and edge cases to instructions before adding subagents.',
        'Add baseline evals that grade tool choice, exit condition, recovery behavior, and unsafe action refusal.',
        'Assign low, medium, or high risk to every tool based on write access, reversibility, permissions, and financial or production impact.',
      ],
    };
  }

• scripts/agent-design-governance.js:22-44 (schema)

  Normalizes raw CLI/API options into structured config, handling kebab-case, camelCase, and parsing booleans/numbers/lists.

  function normalizeOptions(raw = {}) {
    const tools = splitList(raw.tools || raw.toolNames);
    const highRiskTools = splitList(raw['high-risk-tools'] || raw.highRiskTools)
      .concat(tools.filter((tool) => HIGH_RISK_KEYWORDS.test(tool)));
    return {
      workflow: String(raw.workflow || raw.name || 'agent workflow').trim() || 'agent workflow',
      toolCount: parseNumber(raw['tool-count'] || raw.toolCount || tools.length, tools.length),
      similarToolCount: parseNumber(raw['similar-tool-count'] || raw.similarToolCount, 0),
      conditionalBranches: parseNumber(raw['conditional-branches'] || raw.conditionalBranches, 0),
      handoffCount: parseNumber(raw['handoff-count'] || raw.handoffCount, 0),
      autonomyLevel: String(raw['autonomy-level'] || raw.autonomyLevel || 'assisted').trim().toLowerCase(),
      tools,
      highRiskTools: [...new Set(highRiskTools)],
      writeTools: splitList(raw['write-tools'] || raw.writeTools),
      hasBaselineEvals: parseBoolean(raw['baseline-evals'] || raw.hasBaselineEvals, false),
      hasDocs: parseBoolean(raw.docs || raw.hasDocs, false),
      hasExamples: parseBoolean(raw.examples || raw.hasExamples, false),
      hasEdgeCases: parseBoolean(raw['edge-cases'] || raw.hasEdgeCases, false),
      hasToolApprovals: parseBoolean(raw['tool-approvals'] || raw.hasToolApprovals, false),
      hasExitCondition: parseBoolean(raw['exit-condition'] || raw.hasExitCondition, false),
      reversibleActions: parseBoolean(raw['reversible-actions'] || raw.reversibleActions, false),
    };
  }

• scripts/cli-schema.js:208-212 (registration)

  CLI schema registration mapping the 'agent-design-governance' discoverable command to MCP tool 'plan_agent_design_governance'.

  discoveryCommand({
    name: 'agent-design-governance',
    aliases: ['agent-architecture', 'agent-governance-plan'],
    description: 'Decide single-agent vs multi-agent architecture and required eval/tool safeguards',
    mcpTool: 'plan_agent_design_governance',

• adapters/mcp/server-stdio.js:1033-1034 (registration)

  MCP server case statement routing the tool name to the handler function.

  case 'plan_agent_design_governance':
    return toTextResult(buildAgentDesignGovernancePlan(args));

• scripts/agent-design-governance.js:204-211 (helper)

  Exports all helper functions: buildAgentDesignGovernancePlan, formatAgentDesignGovernancePlan, normalizeOptions, scoreInstructions, scoreToolRisk, selectArchitecture.

  module.exports = {
    buildAgentDesignGovernancePlan,
    formatAgentDesignGovernancePlan,
    normalizeOptions,
    scoreInstructions,
    scoreToolRisk,
    selectArchitecture,
  };