veritas-kanban/docs/SOP-shared-resources.md

SOP: Shared Resources Registry

Keep prompts, skills, and guidelines in sync across repos and agents.

---

Why Shared Resources?

"Update once, propagate everywhere." — BoardKit Orchestrator

Without a shared registry:

• Prompts drift between repos
• Agents in different projects behave inconsistently
• SOPs get outdated and forgotten
• New team members copy/paste stale templates

With a shared registry:

• Single source of truth for agent behavior
• Consistent task workflows across all projects
• Easy onboarding (point to the registry)
• Version-controlled evolution

---

Directory Structure

Single Repo (Simple)

my-project/
├── prompt-registry/           # Workflow prompts
│   ├── sprint-planning.md
│   ├── code-review.md
│   └── ...
├── AGENTS.md                  # Agent personality/rules
├── CLAUDE.md                  # Model-specific notes
└── docs/
    └── BEST-PRACTICES.md      # Team patterns

Multi-Repo (Shared Assets)

workspace/
├── shared/                    # Shared across all repos
│   ├── prompt-registry/       # Universal prompts
│   │   ├── sprint-planning.md
│   │   └── cross-model-review.md
│   ├── skills/                # Agent skills/capabilities
│   │   ├── github.md
│   │   └── research.md
│   └── guidelines/            # Universal rules
│       ├── AGENTS-BASE.md
│       └── SECURITY-RULES.md
│
├── project-a/                 # Project-specific
│   ├── AGENTS.md              # Extends shared/guidelines/AGENTS-BASE.md
│   ├── prompt-registry/       # Project-specific prompts
│   │   └── deploy-checklist.md
│   └── ...
│
└── project-b/
    ├── AGENTS.md
    └── ...

---

Mounting Strategies

Strategy 1: Copy + Customize (Recommended for MVP)

Copy shared resources into each repo, customize as needed:

# Initial setup
cp -r ../shared/prompt-registry ./prompt-registry
cp ../shared/guidelines/AGENTS-BASE.md ./AGENTS.md

# Periodically sync
diff -u ../shared/prompt-registry ./prompt-registry
# Review changes, merge manually

Pros: Simple, no tooling required, full control per repo Cons: Manual sync, potential drift

Strategy 2: Symlinks

Link shared resources into each repo:

# From project directory
ln -s ../shared/prompt-registry ./prompt-registry-shared
ln -s ../shared/guidelines/AGENTS-BASE.md ./AGENTS-SHARED.md

Pros: Always in sync, no manual updates Cons: Doesn't work on Windows, requires absolute paths for some tools

Strategy 3: Git Submodules

Maintain shared resources in a separate repo:

# Add submodule
git submodule add https://github.com/org/shared-resources.git shared

# Update
git submodule update --remote

Pros: Versioned, works across orgs Cons: Git submodule complexity

Strategy 4: NPM/pnpm Package (Future)

Publish shared resources as a package:

{
  "dependencies": {
    "@org/agent-resources": "^1.0.0"
  }
}

Pros: Semantic versioning, automatic updates Cons: Requires package infrastructure

---

What to Share

Always Share

• Cross-model review prompt (consistency is critical)
• Security review checklist
• Definition of Done template
• Sprint planning prompt

Share Carefully

• Agent personality (AGENTS.md) — may need project-specific tweaks
• API endpoint references — URLs differ per environment
• Notification channels — project-specific

Don't Share

• Secrets or API keys (use env vars)
• Project-specific business logic
• Team member names/contacts

---

Skill Capability Declarations

Shared resources with type: skill should declare the capabilities they need. Veritas compares declared capabilities with observed static behavior and shows the result in Settings -> Shared Resources -> Skill Capability Profiles.

Preferred frontmatter:

---
capabilities:
  - filesystem.read
  - network.egress
---

Markdown section alternative:

## Declared Capabilities

- `filesystem.read`
- `browser.session`

Canonical ids:

Capability	Use when the skill needs to...
filesystem.read	Read local files or repository content
filesystem.write	Create, edit, move, or delete files
shell.execute	Run shell commands, package scripts, or CLIs
network.egress	Call remote APIs, webhooks, or downloads
credential.access	Read env vars, tokens, secrets, or keychains
external.message	Send chat, email, comments, issues, or PRs
memory.write	Write durable agent memory
task.mutate	Create or change tasks, issues, or PRs
schedule.persist	Create recurring jobs or background watchers
browser.session	Use browser automation or authenticated tabs
mcp.tool	Invoke MCP servers, plugins, or connectors

Rules:

• Avoid * or all; wildcard declarations are treated as review findings.
• Keep declarations narrower than the agent role. The skill declares what it needs, not what the operator could technically grant.
• Run the skill security scanner before installing or updating local skills that include scripts, assets, package manifests, broad triggers, network behavior, credential handling, or persistence hooks. Use POST /api/skills/security/scan or the Maintenance action POST /api/maintenance/skill-security/scan.
• Review Settings -> Shared Resources -> Skill Risk Dashboard before enabling a shared skill. The dashboard joins declared capabilities, observed behavior, persisted scan reports, exceptions, and remediation tasks into one install decision.
• If the profile reports observed behavior that exceeds declarations, create a remediation task from the Shared Resources panel and either narrow the skill or add a reviewer-approved declaration.
• Treat block install decisions as hard stops for remote and cloud workflows unless there is a named owner, clear reason, and future-dated exception.
• Evidence snippets are redacted, but skill authors should still avoid embedding example secrets or real customer data in shared skill text.

Scanner reports are stored as JSON and Markdown under .veritas-kanban/skill-security-scans/ unless persist is false. The scanner checks the local SKILL.md, referenced scripts/ and assets/, package manifests, declared-vs-observed capability mismatches, prompt-injection markers, credential access, exfiltration, unsafe execution, persistence, memory poisoning, overbroad triggers, and unpinned or non-registry dependencies where detectable. Fixture contracts live in server/src/__fixtures__/skill-security/ and cover malicious plus benign cases.

---

Referencing Shared Resources

In Task Descriptions

## Instructions

Follow the standard code review process.
See prompt: `prompt-registry/cross-model-review.md`

In Agent Prompts

You are working on project-a. Use the shared guidelines at `shared/guidelines/AGENTS-BASE.md`
combined with project-specific rules at `AGENTS.md`.

In AGENTS.md

# AGENTS.md

This project extends the base guidelines at `../shared/guidelines/AGENTS-BASE.md`.

## Project-Specific Rules

- Use project-a-specific API at http://localhost:4000
- Deploy requires approval from @project-lead

---

Versioning & Updates

Semantic Versioning for Shared Resources

shared/
├── VERSION                    # 1.2.0
├── CHANGELOG.md               # What changed
└── prompt-registry/
    └── ...

Update Protocol

1. Propose — Create PR/issue in shared resources repo
2. Review — Team reviews impact across all projects
3. Test — Verify in one project first
4. Propagate — Update all repos (manual or via sync script)
5. Announce — Notify team of changes

---

Migration Checklist

Moving from ad-hoc prompts to shared registry:

• Audit existing prompts across all repos
• Identify duplicates and conflicts
• Create canonical versions in shared location
• Update all repos to reference shared versions
• Remove duplicate copies
• Document the new structure in each repo's README
• Train team on update protocol

---

Credit

Shared resources pattern inspired by BoardKit Orchestrator by Monika Voutov.