agent-sh Org Architecture Plan

Tracking doc for the agent-sh GitHub organization buildout. All issues live in agent-sh/agentsys.

Current State

Org: github.com/agent-sh npm scope: @agentsys (claimed on npmjs.com, not yet used) Sites: agentsys | agnix

---

Completed Work

Org Creation & Migration

• Created agent-sh GitHub org (naming: signals shell/terminal tooling, like oven-sh)
• Transferred agentsys repo from avifenesh/agentsys → agent-sh/agentsys
• Transferred agnix repo from avifenesh/agnix → agent-sh/agnix
• Transferred web-ctl repo from avifenesh/web-ctl → agent-sh/web-ctl
• Claimed @agentsys npm scope on npmjs.com
• Updated git remote: origin → https://github.com/agent-sh/agentsys.git

Post-Migration Fixes

• Re-enabled CodeQL default setup on agentsys (disabled by transfer) — PR #248
• Updated all repo links from avifenesh/* → agent-sh/* across 58 files — PR #249
• Updated agnix README links — PR agnix#543
• Re-deployed GitHub Pages for agentsys (Deploy Site workflow)
• Re-deployed GitHub Pages for agnix (Docs Website workflow)
• HTTPS enforcement on agentsys Pages (agnix cert provisioning)

Feature: GitHub Projects as Task Source (#247)

• Added gh-projects as 6th task source in next-task workflow
• needsProjectFollowUp() + getProjectQuestions() for project number/owner
• Input validation (integer check, owner regex, scientific notation rejection)
• Merged via PR #248, issue auto-closed

Research Completed (5 deep guides in agent-knowledge/)

• skill-plugin-distribution-patterns.md — 40 sources: npm/git/vendoring/registry patterns
• monorepo-to-multirepo-migration.md — Subtree splits, version sync, history preservation
• all-in-one-plus-modular-packages.md — 40 sources: AWS SDK v3, Babel, lodash, installer CLIs
• github-org-project-management.md — 15 sources: Projects v2, GraphQL API, automations, real org patterns
• github-org-structure-patterns.md — 18 sources: 7 real orgs analyzed, .github repo, CODEOWNERS, reusable workflows
• oss-org-naming-patterns.md — 24 sources: naming conventions for OSS orgs

web-ctl Architecture Design (#241)

• Researched: terminal browsers, Playwright CLI, session persistence
• Architecture: Skill → scripts/web-ctl.js → Playwright launchPersistentContext
• Security model: AES-256-GCM, OS keyring, HKDF per-session DEK
• Constraint: no MCP server, skill-based (low context cost)
• Updated issue #241 with full architecture spec

Issues Created

• #241 — web-ctl plugin (architecture updated)
• #245 — Org/marketplace strategy (updated with agent-sh decision)
• #246 — GitHub Releases + plugins.json distribution
• #247 — GitHub Projects as task source (merged/closed)

---

Planning Tracks

1. Repo Structure & Plugin Graduation

Issue: #250 Status: Complete Depends on: #256 (cross-repo sync)

Implemented:

• All 19 plugins extracted to standalone repos under agent-sh org
• plugins/ directory removed from agentsys monorepo
• scripts/graduate-plugin.js — extraction script for future plugins
• bin/cli.js updated to fetch plugins from GitHub at install time
• marketplace requires field added for peer dependency tracking
• agent-core sync pipeline extended to all 19 plugin repos

---

2. Plugin Distribution Registry

Issue: #251 Status: Complete Related: #246 (closed, superseded)

Implemented:

• agentsys install <plugin>[@version] with transitive dep resolution
• agentsys remove <plugin> with dep-in-use warnings
• agentsys search [term] with filtered table output
• installed.json manifest at ~/.agentsys/installed.json
• Core version compatibility check (warns on mismatch)
• GitHub tarball fetching with cache at ~/.agentsys/plugins/
• agentsys list and agentsys update subcommands

---

3. GitHub Projects v2 Board

Issue: #252 Status: Complete Depends on: None

Org-level project board spanning all repos. Custom fields, views, automations.

Implemented:

• Board: https://github.com/orgs/agent-sh/projects/1
• Custom fields: Priority (P0-P3), Effort (S/M/L/XL), Component, Target
• Org issue types: task, bug, feature, RFC
• Auto-add workflow in agentsys, agnix, web-ctl (PR #257, agnix #546)
• Auto-archive (configure via board UI: Settings → Workflows)
• Additional views (roadmap, per-repo filtered)

---

4. .github Repo & Shared Infrastructure

Issue: #253 Status: Complete Depends on: None

Org profile README, shared templates, reusable CI workflows, CODEOWNERS.

Implemented:

• Org profile README ("Code does code work. AI does AI work.")
• CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, CODEOWNERS
• Issue templates: bug.yml, feature.yml, config.yml
• Reusable workflows: ci-node.yml, codeql.yml, sync-core.yml
• Pin repos on org profile (GitHub UI only — no API)

---

5. Versioning & Release Coordination

Issue: #254 Status: Complete (baseline established) Depends on: #250 (repo structure) — now complete

Implemented:

• Independent semver for all 13 standalone plugin repos
• marketplace requires field encodes agentsys compatibility range
• agentsys installer uses requires to validate compatibility at install time

Remaining:

• Cross-repo release coordination process (tooling)
• @agentsys npm scope usage (if/when)

---

6. Documentation & Website

Issue: #255 Status: Planning Depends on: #253 (.github repo)

Org landing page, per-repo docs, plugin catalog.

Key decisions needed:

• Unified site vs per-repo (current: per-repo)
• Domain: agent-sh.github.io vs custom domain
• Plugin catalog page design

---

7. Cross-Repo Sync & Compatibility

Issue: #256 Status: Complete (pipeline working) Depends on: None

CI-driven vendor sync from agent-core → all consumer repos.

Implemented:

• Decision: vendored lib/ (not npm) — Claude Code needs plain files
• agent-core repo created + seeded with lib/
• Inline sync workflow (agent-core pushes PR to agentsys on lib/ change)
• Tested end-to-end: push to agent-core → PR opens in agentsys
• Org secrets: SYNC_TOKEN + PROJECT_TOKEN (ALL visibility)
• Add more consumer repos to sync matrix as plugins graduate

---

Pending Work

• Build web-ctl plugin (#241 — architecture done, implementation pending)
• #255 — Documentation & Website (org landing page, plugin catalog)
• Pin repos on org profile (GitHub UI only)
• Auto-archive on project board (board UI)
• Enable HTTPS on agnix Pages (cert provisioning — deploy triggered)
• File GitHub squatting claim for agentsys org name
• Add verified domain to agent-sh org (when domain registered)
• Set org avatar
• Merge link-fix PRs
• Close resolved issues (#245, #246, #250-#254, #256)
• agnix Claude Code plugin (agnix#550)

---

Execution Order

Phase 1 (Immediate — no dependencies):  [DONE]
  #252  GitHub Projects v2 Board
  #253  .github Repo & Shared Infrastructure
  #256  Cross-Repo Sync (research/decision)

Phase 2 (After Phase 1 decisions):  [DONE]
  #250  Repo Structure & Graduation Criteria  ← all 19 plugins extracted
  #254  Versioning & Release Coordination     ← baseline + requires field

Phase 3 (After Phase 2):
  #251  Plugin Distribution Registry          ← next
  #255  Documentation & Website

Parallel (independent):
  #241  web-ctl Plugin Implementation
  #246  Plugin Distribution (Option C — GitHub Releases)

Research Available

---

Created: 2026-02-21 Last updated: 2026-03-25 (Phase 1-3 complete, 6/7 tracks done)