diff --git a/src/app/governance/GovernanceReadiness.tsx b/src/app/governance/GovernanceReadiness.tsx new file mode 100644 index 00000000..f3453ac5 --- /dev/null +++ b/src/app/governance/GovernanceReadiness.tsx @@ -0,0 +1,78 @@ +"use client"; + +import { useMemo, useState } from "react"; + +type ChecklistItem = { + id: string; + label: string; +}; + +type MaturityBand = { + range: [number, number]; + label: string; + guidance: string; +}; + +type Props = { + checklist: ChecklistItem[]; + maturityCriteria: { + basic: MaturityBand; + intermediate: MaturityBand; + advanced: MaturityBand; + }; +}; + +export default function GovernanceReadiness({ checklist, maturityCriteria }: Props) { + const [checked, setChecked] = useState>({}); + + const score = useMemo(() => { + return checklist.reduce((total, item) => total + (checked[item.id] ? 1 : 0), 0); + }, [checklist, checked]); + + const percentage = Math.round((score / checklist.length) * 100); + + const maturity = useMemo(() => { + if (score <= maturityCriteria.basic.range[1]) return maturityCriteria.basic; + if (score <= maturityCriteria.intermediate.range[1]) return maturityCriteria.intermediate; + return maturityCriteria.advanced; + }, [maturityCriteria, score]); + + return ( +
+

Governance Readiness Checklist

+

+ Check each control that is currently implemented in your environment. Score updates instantly. +

+ +
+ {checklist.map((item) => ( + + ))} +
+ +
+

Self-assessment score

+

+ {score}/{checklist.length} ({percentage}%) +

+

+ Maturity: {maturity.label} +

+

{maturity.guidance}

+
+
+ ); +} diff --git a/src/app/governance/accountability/page.tsx b/src/app/governance/accountability/page.tsx new file mode 100644 index 00000000..0d2bc033 --- /dev/null +++ b/src/app/governance/accountability/page.tsx @@ -0,0 +1,145 @@ +/* eslint-disable react/no-unescaped-entities */ + +import type { Metadata } from "next"; +import Link from "next/link"; +import governanceFramework from "@/data/governance-framework.json"; + +type AccountabilityData = { + accountability: { + auditTrailRequirements: string[]; + decisionLoggingPatterns: string[]; + escalationProtocols: string[]; + }; +}; + +export const metadata: Metadata = { + title: "Accountability for Agent Operations — forAgents.dev", + description: + "Audit trails, decision logging, escalation protocols, and human-in-the-loop gates for accountable autonomous agents.", +}; + +const loggingExample = `type DecisionLog = { + decisionId: string; + timestamp: string; + agentId: string; + actorId: string; + action: string; + riskLevel: "low" | "medium" | "high"; + rationale: string; + confidence: number; + policyChecks: { ruleId: string; passed: boolean }[]; + escalationRequired: boolean; +}; + +export async function logDecision(entry: DecisionLog) { + await auditStore.append({ + ...entry, + timestamp: new Date().toISOString(), + }); + + if (entry.riskLevel === "high" || entry.escalationRequired) { + await notifyHumanReviewer({ + decisionId: entry.decisionId, + summary: entry.rationale, + actorId: entry.actorId, + }); + } +}`; + +const hitlGateExample = `export async function runWithHumanGate(input: TaskInput) { + const risk = assessRisk(input); + + if (risk.level !== "high") { + return executeTask(input); + } + + const approval = await requestApproval({ + requestedBy: input.actorId, + summary: input.summary, + timeoutMinutes: 30, + }); + + if (!approval.granted) { + return { status: "blocked", reason: "human_approval_required" }; + } + + return executeTask(input); +}`; + +export default function GovernanceAccountabilityPage() { + const data = governanceFramework as AccountabilityData; + + return ( +
+
+ + ← Back to governance hub + +

+ Accountability Deep Dive +

+

+ Build reliable ownership and defensible evidence across every autonomous decision, so teams don't lose track of responsibility. +

+ +
+
+

Audit trail requirements

+
    + {data.accountability.auditTrailRequirements.map((item) => ( +
  • {item}
    • + ))} +
+
+ +
+

Decision logging patterns

+
    + {data.accountability.decisionLoggingPatterns.map((item) => ( +
  • {item}
    • + ))} +
+
+
+ +
+

Escalation protocols

+
    + {data.accountability.escalationProtocols.map((item) => ( +
  • {item}
    • + ))} +
+
+ +
+

Human-in-the-loop gate design

+

+ Use risk-tiered gates so low-risk actions flow automatically and high-impact actions pause + for reviewer approval. Always enforce explicit deny-by-default behavior when approval is + missing or times out. +

+
    +
  • Define action classes with risk levels and required approver roles.
    • +
  • Set strict decision timeouts and safe fallback behaviors.
    • +
  • Capture reviewer identity, decision reason, and timestamp.
    • +
  • Audit gate bypasses with mandatory post-hoc review.
    • +
+
+ +
+

Code examples: logging agent decisions

+
+ 
{loggingExample}
+
+
+ +
+

Code example: human approval gate

+
+ 
{hitlGateExample}
+
+
+
+
+ ); +} diff --git a/src/app/governance/page.tsx b/src/app/governance/page.tsx index 56e0271a..4ebbf607 100644 --- a/src/app/governance/page.tsx +++ b/src/app/governance/page.tsx @@ -1,392 +1,113 @@ +/* eslint-disable react/no-unescaped-entities */ + +import type { Metadata } from "next"; import Link from "next/link"; -import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"; -import { Badge } from "@/components/ui/badge"; -import { Separator } from "@/components/ui/separator"; +import GovernanceReadiness from "./GovernanceReadiness"; +import governanceFramework from "@/data/governance-framework.json"; + +type Pillar = { + slug: string; + title: string; + description: string; + keyPrinciples: string[]; + maturity: { + basic: string; + intermediate: string; + advanced: string; + }; +}; + +type FrameworkData = { + overview: { + title: string; + description: string; + whyItMatters: string[]; + }; + pillars: Pillar[]; + readinessChecklist: Array<{ id: string; label: string }>; + maturityCriteria: { + basic: { range: [number, number]; label: string; guidance: string }; + intermediate: { range: [number, number]; label: string; guidance: string }; + advanced: { range: [number, number]; label: string; guidance: string }; + }; +}; -export const metadata = { - title: "Governance — forAgents.dev", - description: "How forAgents.dev makes decisions about skill approval, standards, and platform direction through transparent community governance.", - openGraph: { - title: "Governance — forAgents.dev", - description: "How forAgents.dev makes decisions about skill approval, standards, and platform direction through transparent community governance.", - url: "https://foragents.dev/governance", - siteName: "forAgents.dev", - type: "website", - }, +export const metadata: Metadata = { + title: "Agent Governance Framework — forAgents.dev", + description: + "Best-practice governance framework for autonomous agents covering accountability, transparency, safety, and compliance.", }; export default function GovernancePage() { + const data = governanceFramework as FrameworkData; + return (
- - {/* Hero Section */} -
- {/* Subtle aurora background */} -
-
-
-
- -
-

- Governance -

-

- Transparent decision-making for the agent directory -

+
+

Governance Framework Hub

+

+ Agent Governance Framework +

+

+ {data.overview.description} Governance isn't optional once agents can act independently. +

+ +
+

Why governance matters for autonomous agents

+
    + {data.overview.whyItMatters.map((point) => ( +
  • {point}
    • + ))} +
-
- - - - {/* How We Govern Section */} -
-
-
-
-
- 🏛️ -

How We Govern

-
-
-

- forAgents.dev believes in transparent, community-driven governance. Every decision about skill approvals, platform standards, and future direction is made through clear processes that prioritize safety, quality, and agent utility. -

-

- We're not a closed directory — we're a community. Anyone can propose changes, review skills, or participate in governance votes. This open approach ensures the platform serves the entire agent ecosystem, not just a select few. -

-

- Our governance model combines automated checks with human review, community feedback, and transparent voting. The result? A directory you can trust, built by the people who use it. -

-
-
-
-
- - - {/* Skill Approval Process Section */} -
-
-

✅ Skill Approval Process

-

- Five steps from submission to publish -

-
- -
- {[ - { - step: "1", - title: "Submit", - description: "Anyone can submit a skill through our submission form. Include a clear description, documentation, and examples of how agents can use it.", - icon: "📝", - }, - { - step: "2", - title: "Auto-scan", - description: "Our automated system checks for security issues, broken links, malformed metadata, and compliance with basic standards. Most issues are caught here.", - icon: "🤖", - }, - { - step: "3", - title: "Peer Review", - description: "Trusted community reviewers assess quality, usefulness, and agent-friendliness. Reviewers leave feedback and suggest improvements.", - icon: "👥", - }, - { - step: "4", - title: "Community Vote", - description: "The community votes on whether the skill meets our standards. A majority approval (60%+) is required to proceed.", - icon: "🗳️", - }, - { - step: "5", - title: "Publish", - description: "Approved skills are published to the directory and made available through our API, markdown feeds, and machine-readable endpoints.", - icon: "🚀", - }, - ].map((item, index) => ( -
-
-
-
{item.icon}
-
-
- - Step {item.step} - -

- {item.title} -

-
-

- {item.description} -

+
+

Four governance pillars

+
+ {data.pillars.map((pillar) => ( +
+

{pillar.title}

+

{pillar.description}

+ +
+

Key principles

+
    + {pillar.keyPrinciples.map((principle) => ( +
  • {principle}
    • + ))} +
-
-
- ))} -
-
- - - - {/* Standards Committee Section */} -
-
-

🎯 Standards Committee

-

- Trusted members who maintain quality and direction -

-
- -
- {[ - { - role: "Security Lead", - responsibility: "Reviews all skills for security vulnerabilities, malicious code, and unsafe practices before approval.", - icon: "🔒", - }, - { - role: "Documentation Lead", - responsibility: "Ensures all skills have clear, agent-readable documentation with examples and proper metadata.", - icon: "📚", - }, - { - role: "Standards Lead", - responsibility: "Maintains the skill schema, API standards, and platform conventions. Proposes updates as needed.", - icon: "📐", - }, - { - role: "Community Lead", - responsibility: "Coordinates governance votes, manages community feedback, and ensures transparent decision-making.", - icon: "🤝", - }, - { - role: "Quality Lead", - responsibility: "Tests skills for functionality, agent usability, and overall quality. Reports issues and suggests improvements.", - icon: "✨", - }, - ].map((member, index) => ( - - - - {member.icon} - {member.role} - - - -

- {member.responsibility} -

- - - ))} -
-
- - - {/* Proposals Section */} -
-
-
-
- -
-
- 💡 -

Proposals

-
- -

- Want to change how forAgents.dev works? Anyone can propose changes through our RFC (Request for Comments) process. Whether it's a new feature, a change to the approval process, or a shift in platform direction — your voice matters. -

- -
-
- → -
-

1. Draft Your Proposal

-

- Write a clear RFC document explaining the problem, your proposed solution, and why it matters. +

+

+ Basic: {pillar.maturity.basic}

-
-
-
- → -
-

2. Submit for Review

-

- Post your RFC to our GitHub discussions or community forum for feedback and refinement. +

+ Intermediate: {pillar.maturity.intermediate}

-
-
-
- → -
-

3. Community Discussion

-

- The community debates the proposal, suggests improvements, and identifies potential issues. -

-
-
-
- → -
-

4. Vote

-

- After discussion, the community votes. Proposals need 70%+ approval to be implemented. +

+ Advanced: {pillar.maturity.advanced}

-
-
- -
- - Submit an RFC ↗ - - - View Roadmap → - -
-
-
-
- - - - {/* Voting Section */} -
-
-

🗳️ Voting

-

- How governance votes work on forAgents.dev -

-
- - - -
-
-

- 👤 - Who Can Vote? -

-

- Any registered member of the forAgents.dev community with a verified account can participate in governance votes. New members can vote after a 7-day waiting period to prevent vote manipulation. -

-
- - - -
-

- 📊 - Vote Types -

-
-
- - Skill Approval - -

- 60%+ approval required to publish a skill to the directory. -

-
-
- - Platform Changes - -

- 70%+ approval required for major changes to the platform or governance process. -

-
-
- - Committee Elections - -

- Simple majority (50%+) required to elect or remove committee members. -

-
-
-
- - - -
-

- ⏱️ - Voting Period -

-

- All governance votes remain open for 7 days, giving the community ample time to review, discuss, and participate. Votes are final once the period closes. -

-
- - - -
-

- 🔍 - Transparency -

-

- All votes are publicly visible. You can see who voted, how they voted, and the final tally. We believe transparency builds trust and accountability. -

-
-
- - -
- - - - {/* Call to Action */} -
-
-

Join the Governance Process

-

- forAgents.dev belongs to its community. Review skills, propose changes, vote on decisions — your participation makes the platform better for everyone. -

-
- - Submit a Skill - - - Contribute on GitHub - + + ))}
+
+ + + +
+ + Accountability deep dive → + + + Safety patterns → +
-
); } diff --git a/src/app/governance/safety/page.tsx b/src/app/governance/safety/page.tsx new file mode 100644 index 00000000..40439411 --- /dev/null +++ b/src/app/governance/safety/page.tsx @@ -0,0 +1,120 @@ +/* eslint-disable react/no-unescaped-entities */ + +import type { Metadata } from "next"; +import Link from "next/link"; +import governanceFramework from "@/data/governance-framework.json"; + +type SafetyData = { + safety: { + sandboxingStrategies: string[]; + rateLimitingAndCaps: string[]; + rollbackAndKillSwitch: string[]; + incidentResponseTemplate: string[]; + }; +}; + +export const metadata: Metadata = { + title: "Safety Patterns for Agent Systems — forAgents.dev", + description: + "Sandboxing, rate limits, rollback controls, kill-switches, and incident response patterns for safe autonomous agents.", +}; + +const dangerousOpsTestPlan = `# Dangerous Operation Test Plan (Staging) + +1) Build synthetic test data with no customer-sensitive payloads. +2) Enable strict sandbox profile (no external writes, limited network). +3) Run canary scenarios with capped budgets and request rates. +4) Inject failures (timeouts, malformed inputs, policy violations). +5) Validate containment, rollback, and escalation behavior. +6) Promote only after all safety assertions pass.`; + +const incidentTemplate = `Incident ID: +Severity (P0-P3): +Detected At: +Owner: + +Impact Summary: +Affected Systems: +Customer Impact: + +Immediate Containment Actions: +Evidence Preserved: + +Root Cause: +Corrective Actions: +Preventive Actions: + +Communication Log: +Post-Incident Review Date:`; + +export default function GovernanceSafetyPage() { + const data = governanceFramework as SafetyData; + + return ( +
+
+ + ← Back to governance hub + +

+ Safety Patterns +

+

+ Safety controls for minimizing harm while preserving useful agent autonomy, so one bad run doesn't cascade. +

+ +
+
+

Sandboxing strategies

+
    + {data.safety.sandboxingStrategies.map((item) => ( +
  • {item}
    • + ))} +
+
+ +
+

Rate limiting and resource caps

+
    + {data.safety.rateLimitingAndCaps.map((item) => ( +
  • {item}
    • + ))} +
+
+
+ +
+

Rollback and kill-switch patterns

+
    + {data.safety.rollbackAndKillSwitch.map((item) => ( +
  • {item}
    • + ))} +
+
+ +
+

Testing dangerous operations safely

+

+ Never validate high-risk pathways directly in production. Use staged rehearsals with + synthetic data, enforced isolation, and explicit go/no-go safety checks. +

+
+ 
{dangerousOpsTestPlan}
+
+
+ +
+

Incident response playbook template

+
    + {data.safety.incidentResponseTemplate.map((item) => ( +
  • {item}
    • + ))} +
+
+ 
{incidentTemplate}
+
+
+
+
+ ); +} diff --git a/src/data/governance-framework.json b/src/data/governance-framework.json new file mode 100644 index 00000000..680cf8c9 --- /dev/null +++ b/src/data/governance-framework.json @@ -0,0 +1,176 @@ +{ + "overview": { + "title": "Agent Governance Framework", + "description": "A practical governance model for designing, running, and auditing autonomous agents in production environments.", + "whyItMatters": [ + "Autonomous agents can act at speed and scale, so failures can propagate quickly.", + "Governance creates clear ownership for decisions, incidents, and policy exceptions.", + "Structured controls improve trust with users, auditors, and regulators.", + "Maturity-based governance helps teams evolve from ad-hoc controls to resilient operations." + ] + }, + "pillars": [ + { + "slug": "accountability", + "title": "Accountability", + "description": "Define ownership for agent behavior, maintain auditability, and ensure people can intervene before high-impact actions complete.", + "keyPrinciples": [ + "Every autonomous decision maps to an accountable owner.", + "High-risk decisions must have a documented approval path.", + "Escalation paths include named contacts and response SLAs.", + "Decision logs are tamper-evident and reviewable." + ], + "maturity": { + "basic": "Capture who triggered each task and store basic execution logs.", + "intermediate": "Add structured decision logs, approval gates, and regular governance reviews.", + "advanced": "Implement policy-as-code controls, immutable audit trails, and live oversight dashboards." + } + }, + { + "slug": "transparency", + "title": "Transparency", + "description": "Make agent behavior understandable to operators, reviewers, and impacted users through clear explanations and visibility.", + "keyPrinciples": [ + "Expose rationale summaries for non-trivial decisions.", + "Document model/tool versions used per execution.", + "Track confidence, uncertainty, and fallback behavior.", + "Communicate significant incidents and mitigation steps promptly." + ], + "maturity": { + "basic": "Provide basic task status and execution outcomes.", + "intermediate": "Show rationale summaries and confidence indicators in operator views.", + "advanced": "Offer end-to-end observability with explainability, lineage, and stakeholder reporting." + } + }, + { + "slug": "safety", + "title": "Safety", + "description": "Reduce harmful outcomes with sandboxing, guardrails, kill-switches, and staged rollout patterns.", + "keyPrinciples": [ + "Constrain runtime permissions with least privilege defaults.", + "Use hard caps on rate, spend, and resource usage.", + "Support instant pause/rollback and graceful recovery.", + "Test dangerous operations in isolated environments first." + ], + "maturity": { + "basic": "Use input/output filtering and simple execution constraints.", + "intermediate": "Apply environment isolation, rate caps, and operator-controlled emergency stop.", + "advanced": "Adopt multi-layer guardrails, continuous red-team testing, and automated containment workflows." + } + }, + { + "slug": "compliance", + "title": "Compliance", + "description": "Align agent operations with legal, contractual, and industry obligations while preserving evidence for audits.", + "keyPrinciples": [ + "Classify data and enforce policy-based handling rules.", + "Maintain retention and deletion controls for logs and artifacts.", + "Map controls to relevant standards and regulations.", + "Continuously verify and document control effectiveness." + ], + "maturity": { + "basic": "Document applicable requirements and retain core records.", + "intermediate": "Map controls to obligations and run recurring compliance checks.", + "advanced": "Continuously monitor compliance posture with automated evidence collection and alerts." + } + } + ], + "readinessChecklist": [ + { + "id": "owners", + "label": "Each production agent has a named owner and escalation backup." + }, + { + "id": "decision-logs", + "label": "Agent decisions are logged with rationale, risk level, and outcome." + }, + { + "id": "approval-gates", + "label": "High-risk actions require explicit human approval before execution." + }, + { + "id": "sandboxing", + "label": "Dangerous capabilities run in sandboxed environments with least privilege." + }, + { + "id": "resource-caps", + "label": "Rate limits and resource/spend caps are enforced in runtime." + }, + { + "id": "kill-switch", + "label": "Operators can trigger a kill-switch and rollback workflows quickly." + }, + { + "id": "incident-playbook", + "label": "An incident response playbook exists and has been exercised recently." + }, + { + "id": "audit-evidence", + "label": "Audit evidence is retained, queryable, and protected from tampering." + } + ], + "maturityCriteria": { + "basic": { + "range": [0, 3], + "label": "Basic", + "guidance": "Foundational controls exist, but operations are still mostly reactive." + }, + "intermediate": { + "range": [4, 6], + "label": "Intermediate", + "guidance": "Core governance controls are active, with partial automation and regular review." + }, + "advanced": { + "range": [7, 8], + "label": "Advanced", + "guidance": "Governance is proactive, measurable, and deeply integrated into delivery workflows." + } + }, + "accountability": { + "auditTrailRequirements": [ + "Unique execution IDs, actor IDs, and timestamps for every agent action.", + "Immutable records for policy checks, tool calls, and approval outcomes.", + "Versioned prompts, models, and tool manifests for reproducibility.", + "Evidence retention policy aligned with legal and contractual requirements." + ], + "decisionLoggingPatterns": [ + "Capture structured fields: context, alternatives considered, chosen action, and confidence.", + "Attach policy evaluation results and rule IDs used during enforcement.", + "Store before/after state snapshots for high-impact mutations.", + "Tag logs by sensitivity tier for access control and retention." + ], + "escalationProtocols": [ + "Define severity classes with response SLAs and ownership.", + "Automatically page responders when confidence drops or policy checks fail.", + "Freeze risky capabilities until human review is complete.", + "Run post-incident reviews with corrective and preventive actions." + ] + }, + "safety": { + "sandboxingStrategies": [ + "Isolate untrusted execution in ephemeral containers or VMs.", + "Use network egress allowlists and secret-scoped credentials.", + "Apply filesystem and syscall restrictions for tool runtimes.", + "Separate staging and production permissions to prevent lateral impact." + ], + "rateLimitingAndCaps": [ + "Per-user, per-agent, and per-tool request limits.", + "Token, CPU, memory, and execution time budgets.", + "Spend controls for paid APIs and external actions.", + "Adaptive throttling under anomaly detection signals." + ], + "rollbackAndKillSwitch": [ + "Atomic changes with idempotent compensation handlers.", + "Global kill-switch and scoped feature flags for containment.", + "Automated rollback triggers tied to error and risk thresholds.", + "Operator runbooks that define safe restart criteria." + ], + "incidentResponseTemplate": [ + "Detect and classify the incident severity.", + "Contain impact by disabling risky pathways.", + "Preserve evidence and establish timeline.", + "Remediate root cause and validate fix in staging.", + "Communicate status updates and complete post-incident review." + ] + } +}