@magneto/paperclip-plugin

Paperclip plugin for Magneto AI — exposes 24 power skills as Paperclip tools with full governance, audit, and hierarchical agent management.

Features

• 24 Power Skills: All Magneto skills (/think, /plan, /review, /ship, /audit, etc.) as Paperclip tools
• Hierarchical Governance: CEO → Architect → Backend/Frontend/Test agent chains with role-based permissions
• Human-in-the-Loop: High-risk operations trigger Paperclip approval workflows
• Audit Bridge: Syncs Magneto's tamper-evident audit log to Paperclip Activity & Events
• Cost Tracking: Per-agent LLM token budgets with spending alerts
• SOC2 Compliance: Built-in separation of duties, security gates, approval chains
• Sprint Integration: Auto-links Magneto artifacts to Paperclip issues/sprints

Installation

npm install @magneto/paperclip-plugin

Paperclip Configuration

Add to your paperclip.yaml:

plugins:
  - name: '@magneto/paperclip-plugin'
    config:
      magnetoPath: 'magneto'           # Path to magneto CLI
      defaultSprintId: 's-{{date}}'    # Default sprint template
      syncAudit: true                  # Enable audit log sync
      auditSyncIntervalMs: 30000       # Sync every 30s
      companyId: '{{company.id}}'      # Company ID for entries
      verbose: false                   # Debug logging

      # Optional: register only specific skills
      # skillFilter:
      #   - 'magneto.think'
      #   - 'magneto.review'
      #   - 'magneto.ship'

Available Tools

Core Reasoning

| Tool | Description | |------|-------------| | magneto.think | Structured thinking with chain-of-thought | | magneto.plan | Strategic planning with dependencies |

Traceability

| Tool | Description | |------|-------------| | magneto.trace | Requirement-to-code coverage analysis | | magneto.drift | Detect spec-to-code drift | | magneto.qa | Browser-based QA testing |

Cross-Model Review

| Tool | Description | |------|-------------| | magneto.codex.review | Multi-LLM code review with convergence | | magneto.codex.challenge | Adversarial code challenge | | magneto.codex.consult | Multi-model architectural consult |

Safety

| Tool | Description | |------|-------------| | magneto.careful | Warn before destructive commands | | magneto.freeze | Lock edits to specific paths | | magneto.unfreeze | Release freeze lock | | magneto.guard | Combined careful + freeze |

Advanced

| Tool | Description | |------|-------------| | magneto.review | Graph-aware code review | | magneto.investigate | Root-cause debugging with auto-freeze | | magneto.ship | Release automation | | magneto.retro | Sprint retrospective from audit log | | magneto.audit | Read/verify audit log | | magneto.learn | Memory management |

Review Gates

| Tool | Description | |------|-------------| | magneto.plan-ceo-review | Business readiness gate | | magneto.plan-design-review | Architecture readiness gate | | magneto.plan-eng-review | Engineering readiness gate |

Usage Examples

In a Paperclip Agent

# agents/magneto-reviewer.yaml
id: magneto-reviewer
name: "Magneto Code Reviewer"
adapt: cli
tools:
  - magneto.review
  - magneto.trace
  - magneto.codex.review

heartbeat:
  on_issue_assigned:
    - action: invoke
      tool: magneto.review
      args:
        diff: '{{issue.diff_path}}'
        sprint: '{{issue.sprint_id}}'

Programmatic API

import magnetoPlugin from '@magneto/paperclip-plugin';

// Access the plugin API
const api = host.config.get('magneto.api');

// List registered tools
console.log(api.toolProvider.getRegisteredTools());

// Sync audit log manually
await api.auditBridge.syncNow();

Governance & Human-in-the-Loop

Paperclip CEO agents can use Magneto as their governance and safety layer:

Risk Assessment

The plugin automatically assesses risk for each Magneto skill:

| Skill | Risk Level | Auto-Approve | Requires Approval | |-------|-----------|--------------|-------------------| | magneto.audit | Low | Yes | No | | magneto.trace | Low | Yes | No | | magneto.review | Medium | No | Yes | | magneto.ship | High | No | Yes | | magneto.guard | Critical | No | Yes | | magneto.land-and-deploy | Critical | No | Yes |

CEO Agent Workflow

agents:
  - id: ceo-agent
    tools: [magneto.plan-ceo-review, magneto.guard, magneto.ship]
    heartbeat:
      on_issue_labeled:
        # 1. Guard sensitive paths before work
        - tool: magneto.guard
          args: { paths: ['src/payments'] }
        
        # 2. CEO review gate (blocks until approved)
        - tool: magneto.plan-ceo-review
          args: { strict: true }
        
        # 3. Ship with full audit trail
        - tool: magneto.ship
          args: { sprint: 's-20260517' }

Approval Flow

When a high-risk skill is invoked:

1. Risk assessed — Plugin evaluates risk level and factors
2. Approval requested — Event emitted to Paperclip governance system
3. Human review — Board/CEO gets notification in Paperclip UI
4. Decision recorded — Approval/rejection logged to audit trail
5. Execution proceeds — If approved, skill executes with full audit logging

Audit Log Integration

Magneto's tamper-evident audit log (audit.jsonl) syncs to Paperclip Activity:

{
  "actor": "agent-123",
  "action": "magneto.governance.approval.required",
  "payload": {
    "skillId": "magneto.ship",
    "riskLevel": "high",
    "riskFactors": ["production deploy", "tests skipped"]
  },
  "timestamp": "2026-05-17T18:00:00Z",
  "companyId": "acme-corp"
}

This enables:

• Governance: Full traceability of AI actions with human approval
• Compliance: SOC2/HIPAA-ready audit trails with hash verification
• Budget Control: Track costs per agent/skill/sprint
• Retrospectives: Sprint analytics from real data

Hierarchical Agent Governance

For multi-agent teams with CEO → Architect → Dev hierarchy:

# CEO Agent with full authority
- id: ceo-agent
  governance:
    role: ceo
    can_approve_for: ['architect-agent', 'devops-agent', ...]
    blocked_skills: []  # Can do anything

# Architect governs dev teams  
- id: architect-agent
  governance:
    role: architect
    can_approve_for: ['backend-agent', 'frontend-agent']
    blocked_skills: ['magneto.ship']  # Can't ship (SOC2)

# Dev team has limited scope
- id: backend-agent
  governance:
    role: backend
    blocked_skills: ['magneto.ship', 'magneto.guard']
    required_skills: ['magneto.review']  # Must review

See:

• docs/HIERARCHICAL-GOVERNANCE.md — Full governance guide
• examples/company-with-governance.yaml — Production-ready config

Development

npm install
npm run build
npm test

License

MIT - See LICENSE