Opus Vault

Multi-Repo & External Project Support

4 min read

Decisions

  • Pending: Project discovery — manual registration or auto-detect?
  • Pending: Where do external project tasks live — Opus vault or in-repo?
  • Pending: Isolation model — separate worktrees per project or Docker?

User Tasks

Summary

Enable Opus to accept and execute coding tasks on repositories other than itself, transforming it from a self-improving system into a general-purpose coding agency.

Problem / Motivation

  • Currently the entire pipeline (FR-056 orchestrator, FR-058 git workflow, FR-055 sandbox) assumes work happens within the Opus repo.
  • The orchestrator polls vault/10_features/ for FRs — this only contains Opus tasks.
  • Sandbox worktrees are created inside Opus’s git repo — won’t work for external projects.
  • A coding agency that can only work on itself has limited value. The real payoff is “here’s a GitHub repo, implement this feature.”
  • External projects have different languages, test frameworks, CI pipelines, and conventions — the system needs to discover and adapt.

Proposed Solution

A project registry where external repos are registered with metadata (repo URL, language, test command, lint command, conventions). The orchestrator can receive tasks for any registered project, clone/checkout in an isolated workspace, and run the standard pipeline (plan → code → test → review → PR) adapted to that project’s tooling.

Open Questions

1. Project Registration

Question: How are external projects added to Opus?

OptionDescription
A) Registry filesrc/opus/projects/registry.yaml with repo URL, language, commands
B) Auto-detect from GitHubPoint at a GitHub user/org, discover repos
C) Per-task specificationEach task includes repo URL and context

Recommendation: Option A for Phase 1 — explicit is safe. Option C as fallback for ad-hoc tasks.

Decision:

2. Task Location

Question: Where do tasks for external projects live?

OptionDescription
A) Opus vault with project tagvault/10_features/02_new/FR-XXX-project-name-task.md with project: repo-name
B) In the external repoEach registered repo has its own task tracking
C) GitHub IssuesPull tasks from GitHub Issues on registered repos

Recommendation: Option A for Phase 1 (centralized), Option C for Phase 2 (pull from GitHub).

Decision:

3. Project Context Discovery

Question: How does the system learn an external project’s conventions?

OptionDescription
A) Read project filesParse README, pyproject.toml/package.json, CI config, CLAUDE.md if present
B) Manual configUser specifies everything in registry
C) Trial runRun tests/lint, observe what works

Recommendation: Option A + B — auto-detect what’s possible, allow manual overrides.

Decision:

Phase Overview

PhaseDescriptionStatus
Phase 1Project registry + isolated checkout + manual task creation—
Phase 2Auto-detect project conventions + adapted pipeline—
Phase 3GitHub Issues as task source + multi-project scheduling—
Phase 4Project onboarding skill (/onboard-repo)—

Phase 1: Project Registry & Isolation —

Goal: Register external projects and run tasks in isolated workspaces.

File / FeatureDetailsOwnerStatus
src/opus/projects/registry.pyProjectRegistry: load/save project configsopus—
src/opus/projects/registry.yamlProject definitions (repo, language, commands)opus—
src/opus/projects/workspace.pyWorkspaceManager: clone, checkout, cleanupopus—
FR frontmatter fieldproject: <project-name> (default: opus)opus—
Orchestrator updateFR-056 reads project field, sets up correct workspaceopus—

Registry format example:

projects:
  opus:
    repo: local
    path: C:\Users\marij\Opus
    language: python
    test_cmd: pytest
    lint_cmd: ruff check
  my-webapp:
    repo: https://github.com/user/my-webapp
    language: typescript
    test_cmd: npm test
    lint_cmd: npm run lint
    branch_strategy: feature-branches

Phase 2: Convention Auto-Detection —

Goal: Automatically discover project conventions by reading config files.

File / FeatureDetailsOwnerStatus
src/opus/projects/detector.pyConventionDetector: scan for config filesopus—
Detectable signalspackage.json, pyproject.toml, Cargo.toml, go.mod, Makefile, .github/workflows/, CLAUDE.mdopus—
Test command discoveryParse CI config or package manager scriptsmv—
Language detectionFile extension analysis + config filesopus—
Review rules adaptationFR-057 reviewer loads project-specific rulesmv—

Phase 3: GitHub Issues Integration —

Goal: Pull tasks from GitHub Issues on registered repos.

File / FeatureDetailsOwnerStatus
src/opus/projects/github_sync.pyPoll GitHub Issues with specific labels (e.g., opus-task)opus—
Issue → FR conversionCreate FR in vault from GitHub Issueopus—
PR → Issue linkingLink created PRs back to source issuesopus—
Status syncUpdate GitHub Issue when FR status changesopus—

Phase 4: Onboarding Skill —

Goal: /onboard-repo <url> skill that registers a project, auto-detects conventions, and creates an initial configuration.

File / FeatureDetailsOwnerStatus
.claude/skills/onboard-repo/SKILL.mdSkill definitionopus—
Onboarding flowClone → detect → generate registry entry → run smoke test → reportmv—
OutputRegistry entry + summary of detected conventionsopus—

Prerequisites / Gap Analysis

Requirements

RequirementDescription
REQ-0Design doc reviewed and approved
REQ-1FR-056 (Orchestrator) — must support project context
REQ-2FR-055 (Sandbox) — must support external repo isolation
REQ-3FR-058 (Agent Git Workflow) — must work with non-Opus repos
REQ-4FR-009 (Python scaffold) — code infrastructure

Current State

ComponentStatusDetails
OrchestratornewFR-056 assumes Opus-only
SandboxnewFR-055 uses Opus worktrees
Git workflownewFR-058 assumes Opus repo
External repo support—Nothing exists

Gap (What’s missing?)

GapEffortBlocker?
Project registryMediumNo
Workspace isolation for external reposMediumDepends on FR-055
Convention auto-detectionMediumNo
Orchestrator project-awarenessMediumDepends on FR-056

Test

Manual tests

TestExpectedOwnerActualLast
Register external projectAppears in registry, can be referenced in FRsopuspending-
Create task for external projectOrchestrator clones repo and sets up workspaceopuspending-
Auto-detect Python projectFinds pyproject.toml, pytest, ruffopuspending-
Auto-detect Node projectFinds package.json, npm test, eslintopuspending-
/onboard-repo on new repoRegistry entry created, smoke test passesopuspending-

AI-verified tests

ScenarioExpected behaviorVerification method
………

E2E tests

ScenarioAssertion
……

Integration tests

ComponentCoverage
……

Unit tests

ComponentTestsCoverage
………

History

DateEventDetails
2026-03-12CreatedIdentified as gap — Opus only works on itself

References

  • FR-056 (Autonomous Coding Orchestrator) — needs project-awareness
  • FR-055 (Sandboxed Code Execution) — needs external repo isolation
  • FR-058 (Agent Git Workflow) — needs multi-repo support
  • FR-046 (GitHub Integration) — GitHub API access
  • FR-059 (Escalation Policy) — external projects may need stricter policies

Graph View