chore: sync core lib and CLAUDE.md from agent-core#267
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR syncs core library files and CLAUDE.md from the agent-core repository. The sync removes plugin dependency management features (requires and core fields from the schema and discoverPluginsFromMarketplace function) and replaces the project-specific CLAUDE.md with a generic template.
Changes:
- Remove
requiresandcorefields from plugin manifest schema - Remove
discoverPluginsFromMarketplacefunction from discovery module - Replace comprehensive CLAUDE.md (267 lines) with generic template (43 lines)
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| lib/schemas/plugin-manifest.schema.json | Removes requires and core fields from plugin manifest validation schema |
| lib/discovery/index.js | Removes discoverPluginsFromMarketplace function and export |
| CLAUDE.md | Replaces project-specific documentation with generic template, removing critical rules, architecture details, commands, agents, and workflow guidance |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @@ -52,20 +52,6 @@ | |||
| "type": "array", | |||
| "maxItems": 20, | |||
| "uniqueItems": true | |||
There was a problem hiding this comment.
The schema removes the requires and core fields, but bin/cli.js still references these fields in multiple places:
- Line 272-276:
resolvePluginDepschecks forplugin.requiresto resolve dependencies - Line 725-728:
checkCoreCompatchecks forpluginEntry.coreto validate version compatibility - Line 1020:
removePluginchecksentry.requiresto warn about dependent plugins
While the current marketplace.json doesn't use these fields, removing them from the schema without updating bin/cli.js creates an inconsistency. Either:
- The schema should retain these fields (if they're still needed for future use), OR
- The bin/cli.js code should be updated to remove references to these fields (if dependency management is being deprecated)
Suggested change
| "uniqueItems": true | |
| "uniqueItems": true | |
| }, | |
| "requires": { | |
| "type": "array", | |
| "items": { | |
| "type": "string" | |
| } | |
| }, | |
| "core": { | |
| "type": "string" |
| })); | ||
| } | ||
|
|
||
| /** |
There was a problem hiding this comment.
The discoverPluginsFromMarketplace function is removed, but there's no indication this function was being used anywhere. However, the memory from previous agent interactions indicates that .claude-plugin/marketplace.json is consumed by agentsys CLI, and the function's docstring suggests it was designed for "the post-extraction world where plugins/ no longer exists in agentsys."
Given that the current architecture shows "plugins/ → 0 plugins" (all plugins are now in standalone repos), this removal might be premature if the function was meant to support discovering plugins from marketplace.json in standalone repos. Verify that plugin discovery still works correctly in repos that don't have a plugins/ directory.
CLAUDE.md
Outdated
Comment on lines
1
to
43
| <!-- AUTO-GENERATED by agent-core sync. Do not edit directly. --> | ||
| # agentsys | ||
|
|
||
| > **Cross-tool compatible**: This file works as CLAUDE.md (Claude Code) and can be copied to AGENTS.md for OpenCode, Codex, and other AI tools. | ||
| > A modular runtime and orchestration system for AI agents - works with Claude Code, OpenCode, and Codex CLI | ||
|
|
||
| <project-memory> | ||
| ## Critical Rules | ||
|
|
||
| <critical-rules> | ||
| ## Critical Rules (Priority Order) | ||
| 1. **Plain text output** - No emojis, no ASCII art. Use `[OK]`, `[ERROR]`, `[WARN]`, `[CRITICAL]` for status markers. | ||
| 2. **No unnecessary files** - Don't create summary files, plan files, audit files, or temp docs. | ||
| 3. **Task is not done until tests pass** - Every feature/fix must have quality tests. | ||
| 4. **Create PRs for non-trivial changes** - No direct pushes to main. | ||
| 5. **Always run git hooks** - Never bypass pre-commit or pre-push hooks. | ||
| 6. **Use single dash for em-dashes** - In prose, use ` - ` (single dash with spaces), never ` -- `. | ||
| 7. **Report script failures before manual fallback** - Never silently bypass broken tooling. | ||
| 8. **Token efficiency** - Be concise. Save tokens over decorations. | ||
|
|
||
| 1. **Production project** - Real users depend on this. Test thoroughly and verify all edge cases before committing. | ||
| *WHY: Breaking changes affect all plugin users immediately.* | ||
|
|
||
| 2. **Plugin for OTHER projects** - Optimize for plugin users, not internal dev convenience. | ||
| *WHY: Every decision must improve the experience for developers using this in their repos.* | ||
|
|
||
| 3. **Use CHANGELOG.md for completion tracking** - MUST use CHANGELOG.md for release notes. NEVER create `*_AUDIT.md`, `*_SUMMARY.md`, `*_COMPLETION.md` files. | ||
| *WHY: Summary files clutter repos and add no value. Report completion verbally.* | ||
|
|
||
| 4. **Unless** it is a very small change of max few lines, or an urgent hotfix, **MUST create PRs for all changes** - No direct pushes to main. | ||
| *WHY: PRs enable reviews, CI checks, and rollback if needed. Direct pushes are risky.* | ||
|
|
||
| 5. **PR reviews** - Wait 3 min for auto-reviewers, address ALL comments (Copilot, Claude, Gemini, Codex). | ||
| *WHY: Skipping comments leads to merged issues. Every comment must be addressed or explained.* | ||
|
|
||
| 6. **Read checklists BEFORE multi-file changes** - **MUST** read the relevant checklist before starting: | ||
| - **Cross-platform work → `checklists/cross-platform-compatibility.md`** (MASTER REF) | ||
| - Release → `checklists/release.md` | ||
| - New command → `checklists/new-command.md` | ||
| - New agent → `checklists/new-agent.md` | ||
| - New skill → `checklists/new-skill.md` | ||
| - New lib module → `checklists/new-lib-module.md` | ||
| - OpenCode plugin update → `checklists/update-opencode-plugin.md` | ||
| - Repo map changes → `checklists/repo-map.md` | ||
| *WHY: Multi-file changes have hidden dependencies. Checklists prevent missed updates.* | ||
|
|
||
| 7. **Especially Before release, and when delivering ANY work** - Check the relevant checklist for completion requirements: | ||
| - Identify which checklist applies to your work (see rule #6) | ||
| - Go through EVERY item in that checklist and apply it (e.g. run commands, which files to bump versions in, etc) | ||
| - Run the `/enhance` command on new or modified commands, agents, skills, hooks or prompts | ||
| - Verify cross-platform compatibility (OpenCode + Codex) | ||
| - Update `bin/cli.js` mappings if new command/agent added | ||
| - Only mark complete after ALL checklist items are done | ||
| *WHY: Checklists exist because we kept missing things. They are the definition of "done".* | ||
|
|
||
| 8. **Use plain text markers** - MUST use `[OK]`, `[ERROR]`, `[WARN]`, `[CRITICAL]` for status. NEVER use emojis or ASCII art boxes. | ||
| - Save tokens - conciseness and clarity over decorations | ||
| - Use markdown formatting instead of decorative borders | ||
| *WHY: Emojis and ASCII art waste tokens. AI models parse plain text better.* | ||
|
|
||
| 9. **gh/git on Windows** - Escape `$` as `\$` in GraphQL queries, avoid `!=` in jq (use `== "A" or == "B"`). | ||
| - `gh pr checks` uses `state` not `conclusion` - returns UPPERCASE: `SUCCESS`, `FAILURE`, `PENDING` | ||
| - Single quotes unreliable - use double quotes with escaped inner quotes | ||
| *WHY: Windows shell interprets $ and ! differently. These cause silent failures.* | ||
|
|
||
| 10. **Always run git hooks** - Run all pre-commit and pre-push hooks. If a hook blocks, fix the reported issue. | ||
| - Hooks catch problems before they reach the repo | ||
| - Fix the root cause, then retry | ||
| *WHY: Hooks are safety nets. Bypassing them defeats their purpose.* | ||
|
|
||
| 11. **Argument hints use `[]` not `<>`** - In `argument-hint` frontmatter, use `[arg]` for optional args, not `<arg>`. | ||
| - Correct: `argument-hint: "[path] [--fix] [--target [target]]"` | ||
| - Wrong: `argument-hint: "[path] [--fix] [--target <target>]"` | ||
| *WHY: Consistent with Claude Code conventions. Angle brackets are ambiguous.* | ||
|
|
||
| 12. **Fix all test failures** - NEVER skip or ignore a failing test because it's "out of scope" or "pre-existing". Always fix it. | ||
| - If a test fails during your work, fix it before proceeding | ||
| - No test is someone else's problem | ||
| *WHY: Skipping failures erodes test trust. Every green run must mean everything works.* | ||
|
|
||
| 13. **Report script failures before manual fallback** - When any project script fails (npm test/run/build, scripts/*, agentsys-dev, node bin/dev-cli.js), you MUST: | ||
| - Report the failure with exact error output to the user | ||
| - Diagnose the root cause of the failure | ||
| - Fix the script/tooling issue, not work around it manually | ||
| - NEVER silently fall back to doing the work by hand | ||
| *WHY: Silent fallbacks mask broken tooling. A failed script needs fixing, not bypassing.* | ||
| </critical-rules> | ||
|
|
||
| <architecture> | ||
| ## Architecture | ||
|
|
||
| <!-- GEN:START:claude-architecture --> | ||
| ``` | ||
| lib/ → Shared library (vendored to plugins) | ||
| plugins/ → 0 plugins, 10 agents (0 file-based + 10 role-based), 0 skills | ||
| adapters/ → Platform adapters (opencode-plugin/, opencode/, codex/) | ||
| checklists/ → Action checklists (9 files) | ||
| bin/cli.js → npm CLI installer | ||
| ``` | ||
|
|
||
| | Plugin | Agents | Skills | Purpose | | ||
| |--------|--------|--------|---------| | ||
| <!-- GEN:END:claude-architecture --> | ||
|
|
||
| > Note: `plugins/ → 0 plugins` is correct — all 14 plugins now live in standalone repos under | ||
| > the [agent-sh](https://github.com/agent-sh) org. The ecosystem-wide counts (14 plugins, | ||
| > 43 agents, 30 skills) reflect all repos combined. agentsys is the marketplace and installer. | ||
|
|
||
| **Pattern**: `Command → Agent → Skill` (orchestration → invocation → implementation) | ||
| </architecture> | ||
|
|
||
| <commands> | ||
| ## Commands | ||
|
|
||
| ### Core Workflow | ||
| - `/next-task` - Master workflow: task → implementation → PR → merge | ||
| - `/ship` - PR creation, CI monitoring, merge | ||
| - `/enhance` - Run all enhancement analyzers | ||
|
|
||
| ### Analysis | ||
| - `/audit-project` - Multi-agent code review | ||
| - `/deslop` - Clean AI slop patterns | ||
| - `/drift-detect` - Compare plan vs implementation | ||
| - `/perf` - Performance investigation | ||
| - `/repo-map` - Generate AST-based repo map | ||
|
|
||
| ### Learning | ||
| - `/learn` - Research topic online, create learning guide with RAG index | ||
|
|
||
| ### Linting | ||
| - `/agnix` - Lint agent configs (SKILL.md, CLAUDE.md, hooks, MCP) | ||
|
|
||
| ### Maintenance | ||
| - `/sync-docs` - Update documentation to match code | ||
|
|
||
| ### Dev Commands | ||
| ```bash | ||
| # Local dev CLI (when developing agentsys itself) | ||
| npx agentsys-dev status # Project health (version, counts, branch) | ||
| npx agentsys-dev validate # Run all validators | ||
| npx agentsys-dev validate plugins # Run single validator | ||
| npx agentsys-dev bump <version> # Bump all version files (e.g., 3.7.3) | ||
| npx agentsys-dev test # Run test suite | ||
| npx agentsys-dev preflight # Change-aware checklist enforcement | ||
| npx agentsys-dev preflight --all # Run all checks | ||
| npx agentsys-dev preflight --release # All checks + release extras | ||
| npx agentsys-dev gen-docs # Auto-generate doc sections | ||
| npx agentsys-dev gen-docs --check # Validate docs are fresh (CI) | ||
| npx agentsys-dev expand-templates # Expand template markers in agents | ||
| npx agentsys-dev expand-templates --check # Validate templates are fresh (CI) | ||
| npx agentsys-dev new plugin <name> # Scaffold new plugin | ||
| npx agentsys-dev new agent <name> --plugin=<plugin> # Scaffold new agent | ||
| npx agentsys-dev new skill <name> --plugin=<plugin> # Scaffold new skill | ||
| npx agentsys-dev new command <name> --plugin=<plugin> # Scaffold new command | ||
| npx agentsys-dev --help # Show all commands | ||
|
|
||
| # Alternative: direct invocation | ||
| node bin/dev-cli.js <command> | ||
|
|
||
| # npm aliases still work: | ||
| npm test # Run tests (do before commits) | ||
| npm run validate # All validators via dev-cli | ||
| npm run preflight # Change-aware preflight checks | ||
| npm run preflight:all # All preflight checks | ||
| npm run preflight:release # Release preflight | ||
| npm run gen-docs # Auto-generate documentation | ||
| npm run gen-docs:check # Check if docs are stale | ||
| npm run expand-templates # Expand agent templates | ||
| npm run expand-templates:check # Check if templates are stale | ||
| npm run new:plugin # Scaffold new plugin | ||
| npm run new:agent # Scaffold new agent | ||
| npm run new:skill # Scaffold new skill | ||
| npm run new:command # Scaffold new command | ||
| npm run bump <version> # Bump versions via dev-cli | ||
| npm pack # Build package | ||
| agentsys # Run installer | ||
| ``` | ||
| </commands> | ||
|
|
||
| <agents> | ||
| ## Agents | ||
|
|
||
| 40 agents across 11 plugins. Key agents by model: | ||
|
|
||
| | Model | Agents | Use Case | | ||
| |-------|--------|----------| | ||
| | **opus** | planning, implementation, perf-orchestrator, debate-orchestrator | Complex reasoning, judgment | | ||
| | **sonnet** | exploration, learn, task-discoverer, delivery-validator, ci-fixer, deslop-agent, reporters | Validation, pattern matching | | ||
| | **haiku** | worktree-manager, ci-monitor, simple-fixer | Mechanical execution | | ||
|
|
||
| See [README.md](./README.md#command-details) and [docs/reference/AGENTS.md](./docs/reference/AGENTS.md) for full agent list. | ||
| </agents> | ||
|
|
||
| <skills> | ||
| ## Skills | ||
|
|
||
| 26 skills across plugins. Agents invoke skills for reusable implementation. | ||
|
|
||
| | Category | Key Skills | | ||
| |----------|------------| | ||
| | Workflow | `orchestrate-review`, `discover-tasks`, `validate-delivery` | | ||
| | Enhancement | `enhance-*` (9 skills for plugins, agents, docs, prompts, hooks) | | ||
| | Performance | `baseline`, `benchmark`, `profile`, `theory-tester` | | ||
| | Cleanup | `deslop`, `sync-docs`, `drift-analysis`, `repo-mapping` | | ||
|
|
||
| See [README.md](./README.md#skills) for full skill list. | ||
| </skills> | ||
|
|
||
| <state-files> | ||
| ## State Files | ||
|
|
||
| | File | Location | Purpose | | ||
| |------|----------|---------| | ||
| | `tasks.json` | `{stateDir}/` | Active task registry | | ||
| | `flow.json` | `{stateDir}/` (worktree) | Workflow progress | | ||
| | `preference.json` | `{stateDir}/sources/` | Cached task source | | ||
| | `suppressions.json` | `~/.<claude\|opencode\|codex>/enhance/` | Auto-learned suppressions | | ||
|
|
||
| Platform-aware state directory: | ||
| - Claude Code: `.claude/` | ||
| - OpenCode: `config/.opencode/` | ||
| - Codex: `.codex/` | ||
| </state-files> | ||
|
|
||
| <workflow-agents> | ||
| ## Workflow Agents (MUST-CALL) | ||
|
|
||
| Cannot skip in /next-task: | ||
| - `exploration-agent` → before planning | ||
| - `planning-agent` → before implementation | ||
| - **Phase 9 review loop** → MUST use orchestrate-review skill | ||
| - `delivery-validator` → before sync-docs:sync-docs-agent | ||
| - `sync-docs:sync-docs-agent` → before /ship | ||
| </workflow-agents> | ||
|
|
||
| <pr-auto-review> | ||
| ## PR Auto-Review | ||
|
|
||
| 4 reviewers: Copilot, Claude, Gemini, Codex | ||
|
|
||
| 1. Wait 3 min after PR creation (initial auto-reviews) | ||
| 2. Claude-review may take 10+ min - wait for it | ||
| 3. Read ALL comments | ||
| 4. Address EVERY comment | ||
| 5. Iterate until zero unresolved | ||
| </pr-auto-review> | ||
|
|
||
| <model-selection> | ||
| ## Model Selection | ||
|
|
||
| | Model | When to Use | | ||
| |-------|-------------| | ||
| | **Opus** | Complex reasoning, analysis where imperfection compounds | | ||
| | **Opus** | Complex reasoning, analysis, planning | | ||
| | **Sonnet** | Validation, pattern matching, most agents | | ||
| | **Haiku** | Mechanical execution, no judgment needed | | ||
| </model-selection> | ||
|
|
||
| <priorities> | ||
| ## Core Priorities | ||
|
|
||
| 1. User DX (plugin users) | ||
| 1. User DX (plugin users first) | ||
| 2. Worry-free automation | ||
| 3. Token efficiency | ||
| 4. Quality output | ||
| 5. Simplicity | ||
| </priorities> | ||
|
|
||
| <end-reminder> | ||
| **REMEMBER**: | ||
| - Use CHANGELOG.md for completion tracking (not summary files) | ||
| - BEFORE starting → Read the relevant checklist (`checklists/*.md`) | ||
| - BEFORE delivering any work, especially releases → Go through that checklist item by item | ||
| - 3 platforms: Claude Code + OpenCode + Codex - ALL must work | ||
| - Agent/Skill pattern: Agents invoke skills, skills have implementation | ||
| - Create PRs for non-trivial changes | ||
| </end-reminder> | ||
| ## Dev Commands | ||
|
|
||
| ```bash | ||
| npm test # Run tests | ||
| npm run validate # All validators | ||
| ``` | ||
|
|
||
| ## References | ||
|
|
||
| </project-memory> | ||
| - Part of the [agentsys](https://github.com/agent-sh/agentsys) ecosystem | ||
| - https://agentskills.io |
There was a problem hiding this comment.
The CLAUDE.md file has been dramatically simplified from 267 lines to 43 lines, removing critical project-specific information including:
- All critical rules (13 detailed rules → 8 generic rules)
- Architecture details and plugin/agent/skill counts
- Complete command list (only 2 dev commands remain)
- Agent model selection guidance (40 agents → simplified to 3 model types)
- Skills documentation (26 skills)
- State files reference
- Workflow enforcement rules
- PR auto-review process
- Cross-platform compatibility reminders
While the PR description states this is a "sync from agent-core," the resulting file appears to be a generic template rather than project-specific documentation. This could significantly impact developer productivity and workflow compliance. Verify this is intentional and that the removed content is not needed for this repository's development workflow.
Comment on lines
6
to
16
| ## Critical Rules | ||
|
|
||
| <critical-rules> | ||
| ## Critical Rules (Priority Order) | ||
| 1. **Plain text output** - No emojis, no ASCII art. Use `[OK]`, `[ERROR]`, `[WARN]`, `[CRITICAL]` for status markers. | ||
| 2. **No unnecessary files** - Don't create summary files, plan files, audit files, or temp docs. | ||
| 3. **Task is not done until tests pass** - Every feature/fix must have quality tests. | ||
| 4. **Create PRs for non-trivial changes** - No direct pushes to main. | ||
| 5. **Always run git hooks** - Never bypass pre-commit or pre-push hooks. | ||
| 6. **Use single dash for em-dashes** - In prose, use ` - ` (single dash with spaces), never ` -- `. | ||
| 7. **Report script failures before manual fallback** - Never silently bypass broken tooling. | ||
| 8. **Token efficiency** - Be concise. Save tokens over decorations. | ||
|
|
There was a problem hiding this comment.
The simplified CLAUDE.md no longer includes the numbered "Critical Rules" that are referenced elsewhere in the codebase:
scripts/setup-hooks.js:24references "CLAUDE.md Critical Rule Implement /ship command #7"scripts/setup-hooks.js:56references "CLAUDE.md Critical Rule Implement /ship command #7 requires running /enhance"changelogs/CHANGELOG-v3.md:341references "CLAUDE.md Critical Rule Implement /ship command #7"meta/skills/maintain-cross-platform/SKILL.md:466references "CLAUDE.md Critical Rule Implement /ship command #7"
The new CLAUDE.md has 8 rules but they are not numbered, and the content is different. This creates a documentation inconsistency where scripts and changelogs reference specific numbered rules that no longer exist. Either update the references or restore the numbered critical rules structure.
CLAUDE.md
Outdated
| @@ -1,267 +1,43 @@ | |||
| # Project Memory: AgentSys | |||
| <!-- AUTO-GENERATED by agent-core sync. Do not edit directly. --> | |||
There was a problem hiding this comment.
The file is marked as "AUTO-GENERATED by agent-core sync. Do not edit directly." This warning is problematic because:
- This is the agentsys repository itself, not a downstream consumer
- The file contains agentsys-specific references (line 42: "Part of the agentsys ecosystem")
- Other parts of the codebase reference CLAUDE.md content (e.g., scripts/setup-hooks.js references "Critical Rule Implement /ship command #7")
- This creates confusion about whether developers should edit this file or not
If CLAUDE.md is truly auto-generated from agent-core, then either:
- The sync process should preserve agentsys-specific content, OR
- The warning should be removed since this IS the source repository, OR
- A different mechanism should be used to maintain project-specific documentation
Suggested change
| <!-- AUTO-GENERATED by agent-core sync. Do not edit directly. --> | |
| <!-- Source of truth for agent-core sync. Edit in this agentsys repo; changes may be synced to downstream consumers. --> |
| "type": "string", | ||
| "pattern": "^>=\\d+\\.\\d+\\.\\d+$", | ||
| "description": "Minimum agent-core version required" | ||
| } |
There was a problem hiding this comment.
The schema removes the requires and core fields, but these are documented features in CHANGELOG.md line 22: "Marketplace requires field — .claude-plugin/marketplace.json now supports a requires field per plugin entry to declare the minimum agentsys installer version required."
Removing schema support for a documented feature without:
- Documenting the removal in CHANGELOG.md
- Updating bin/cli.js to remove code that uses these fields
- Verifying no marketplace entries use these fields
This creates an inconsistent state where the feature is documented as available but the schema no longer supports it.
- Expand CLAUDE.md rule #7 with detailed body text (fixes 3 test assertions) - Remove auto-generated comment from CLAUDE.md - Clean up dead requires/core code in bin/cli.js to match schema removal
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Automated sync of lib/ and CLAUDE.md from agent-core.