# OpenAgents Control Repository Management Plan

## Product Definition

OpenAgents Control should be maintained as a **human-controlled orchestration and context layer for AI-assisted work**, initially focused on software development.

Its current product promise is:

1. **Project-aware output** — agents load version-controlled project and team patterns before acting.
2. **Human control** — agents propose plans and request approval before execution or destructive operations.
3. **Editable behavior** — agents and context remain inspectable Markdown/configuration rather than hidden proprietary behavior.
4. **Repeatability** — teams can share context, agents, and workflows through source control.
5. **Behavioral validation** — the eval framework checks approval gates, context loading, tool use, and failure handling.
6. **Distribution** — a registry, profiles, installer, and package tooling distribute supported components.
7. **Model flexibility** — users can choose providers and models without redesigning the workflow.

OpenCode is the primary runtime today. Claude Code support is beta. Cursor, Windsurf, a larger package manager, marketplace, lockfile, and broad multi-IDE management are strategic directions, not fully adopted current commitments.

## Primary Users

### Current priority

1. **Solo developers** who want safe setup, predictable behavior, and quick recovery.
2. **Team leads** who need shared standards, reproducible configuration, and controlled changes.

### Later users

- Open-source maintainers who publish and review community components.
- Content creators who would require simpler or graphical interfaces.
- Enterprise administrators, which should remain post-v1 rather than driving current complexity.

## Product Principles

Every feature should pass these tests:

- **Safe by default:** no silent package installs, destructive cleanup, overwrites, or remote execution.
- **Previewable:** risky operations show planned effects before execution.
- **Recoverable:** backups, atomic writes, rollback, and clear failure states.
- **Local-first:** project configuration wins when working in a repository.
- **User-owned customization:** updates must not destroy unmanaged or modified files.
- **One source of truth:** avoid independent installer, resolver, model, and metadata implementations.
- **Evidence-driven:** tests must exercise the behavior actually changed.
- **Focused changes:** large architectural ideas are split into reviewable vertical slices.

## Current Architecture

The implemented repository has four central systems:

1. **Agents and subagents** in `.opencode/agent/` define orchestrators and delegated specialists.
2. **Context** in `.opencode/context/` records standards, workflows, and project knowledge discovered lazily by ContextScout.
3. **Registry and profiles** in `registry.json` and `.opencode/profiles/` describe distributable components and dependencies.
4. **Evaluation and validation** in `evals/` and `scripts/` test agent behavior and repository structure.

Additional systems include the shell installer/updater, Claude Code plugin, compatibility package, task management, skills, and experimental ability enforcement.

## Strategic Decisions Required

Record these as ADRs before restarting the large v1 refactor:

1. **Installer authority:** Bash, Node/Bun CLI, or one shared resolver consumed by all frontends.
2. **File ownership:** define generated, OAC-owned, user-edited, and unmanaged files.
3. **Runtime:** supported Node versions and whether Bun is required, optional, or build-only.
4. **Registry versioning:** separate package version, registry data version, and schema version.
5. **Agent metadata:** decide between strict OpenCode frontmatter and centralized metadata.
6. **Permission syntax:** adopt singular `permission` and retire contradictory examples.
7. **Model configuration:** inherited runtime defaults, per-agent values, or a central optional router.
8. **Multi-IDE scope:** define what is native, converted, or intentionally unsupported.
9. **Editable versus declarative installs:** define how Nix/immutable modes coexist with editable agents.
10. **Release model:** version bump, npm publication, GitHub release, rollback, and support policy.

## Roadmap

### Phase 0 — Security and governance

- Fix privileged PR workflow execution.
- Fix broken PR change detection and add meaningful test jobs.
- Add `SECURITY.md` and enable private vulnerability reporting.
- Define required checks and branch protection.
- Establish the source-of-truth hierarchy for code, registry, docs, context, and planning proposals.

### Phase 1 — Stabilize 0.7.x

- Process the six focused merge candidates from the July PR audit.
- Fix installer, context-path, updater, and task-management regressions through focused replacements.
- Correct stale README, roadmap, changelog, version, and context documentation.
- Establish Linux, macOS, Windows/Git Bash, and worktree validation where relevant.
- Publish one stabilization release after installation and update smoke tests pass.

### Phase 2 — Decide the v1 architecture

- Write and approve the ten ADRs above.
- Define a shared file-ownership and installation contract.
- Reconcile the shell installer with the existing CLI work from #259.
- Define migration from current installations.
- Decide which package-refactor features are truly v1: onboarding, discovery, lockfile, rollback, security, and multi-IDE support.

### Phase 3 — Deliver v1 incrementally

- Build vertical slices, not one large branch.
- Start with safe initialization and ownership tracking.
- Add doctor/status and rollback before broad update automation.
- Add reproducible lockfiles before community distribution.
- Add marketplace/community features only after signing, verification, and contribution governance exist.

## PR Management Policy

### Intake

Every PR must have:

- A linked issue or a clear reason why one is unnecessary.
- One problem and one coherent outcome.
- Scope, risk, user impact, and test plan.
- Conventional title.
- Documentation and migration notes when behavior changes.

### Required review states

- **Needs triage** — metadata and ownership incomplete.
- **Ready for review** — checks pass and acceptance criteria are clear.
- **Changes requested** — actionable blockers recorded.
- **Approved** — no unresolved critical findings.
- **Deferred** — valid but not aligned with the current roadmap.
- **Superseded/close** — stale, duplicated, or replaced.

### Size policy

- Small fix: ideally fewer than 200 changed lines.
- Feature: one independently testable vertical slice.
- Architecture program: tracking issue plus multiple PRs; never a single 10k–20k-line merge.

### Review SLA

- Security: same day.
- User-blocking bug: 2 business days.
- Small maintenance PR: 5 business days.
- Feature or architecture PR: triage within 7 days; schedule separately.

## Issue Management Policy

- Triage new issues weekly.
- Label by type, area, priority, and status.
- Close answered questions after confirmation or a reasonable inactivity period.
- Merge duplicates into one canonical issue.
- Require reproduction details for bugs before implementation unless impact is urgent.
- Convert large features into an epic with explicit decisions and vertical slices.
- Add progress comments at least every two weeks for active work.

## Worktree and Branch Policy

- Use one worktree per active PR or focused issue.
- Keep worktrees outside the main checkout in a single managed parent directory.
- Never force-remove a dirty worktree by default.
- Never delete Docker volumes, environment files, or branches as an implicit cleanup step.
- Never run dependency lifecycle scripts automatically when checking out an untrusted PR.
- Remove worktrees only after verifying clean state and merged/abandoned status.
- Delete remote branches after merge unless retained for an active release or long-running program.
- Review stale branches monthly.

## Validation Matrix

| Changed area | Minimum validation |
|---|---|
| Agent/context | Frontmatter validation, registry validation, context links, focused eval |
| Registry/profile | TypeScript and Bash validator tests, dependency resolution, profile install smoke test |
| Installer/updater | Shell syntax, unit fixtures, clean install, upgrade, collision, rollback, platform matrix |
| Eval framework | TypeScript build, Vitest, suite validation, focused SDK test |
| Plugin | Manifest validation, installed-plugin discovery, command/skill smoke test |
| Task/worktree tooling | Shell tests, normal checkout, linked worktree, dirty-state and containment tests |
| Package/CLI | Typecheck, unit tests, `npm pack`, clean global/local install, migration test |
| Workflow | Least-privilege review, fork simulation, required-check behavior |
| Documentation | Link validation, version/current-command review |

## Release Management

Before release:

1. Confirm approved scope and semantic version.
2. Run the complete validation matrix for affected systems.
3. Reconcile `VERSION`, package versions, registry/schema versions, and lockfiles.
4. Update a chronological, user-focused changelog.
5. Verify package contents with `npm pack`.
6. Test fresh install and update from the previous supported version.
7. Publish npm artifacts and GitHub release through a documented, auditable runbook.
8. Verify installation from the published artifacts.
9. Record rollback instructions and known issues.

## Maintenance Cadence

### Weekly

- Triage new issues and PRs.
- Review security and user-blocking reports first.
- Keep no more than three implementation items actively in progress.
- Update owners, status, and blockers.

### Monthly

- Review stale PRs, issues, branches, and worktrees.
- Audit dependency and action updates.
- Check README, roadmap, changelog, and context drift.
- Review release readiness and health metrics.

### Quarterly

- Reconfirm product priorities and supported platforms.
- Review accepted ADRs and deprecations.
- Audit installer/resolver duplication and maintenance cost.
- Review contributor experience and security posture.

## Health Metrics

Track:

- Median time to first PR review.
- Open security and user-blocking issues.
- PRs older than 30 days without a decision.
- Percentage of PRs with meaningful behavioral tests.
- Install/update success by supported platform.
- Documentation pages known to be stale.
- Number of active versus stale branches and worktrees.
- Release frequency and rollback incidents.

## Source-of-Truth Order

Until formal ADRs are adopted, use:

1. Executable code, package manifests, registry, and active workflows.
2. Root README for current public positioning.
3. Package-level READMEs for implemented package behavior.
4. Current repository standards and context.
5. Contributor guides and historical audits.
6. `docs/archive/planning/` as archived historical proposals only.