Skip to content

AGENTS.md

Latest commit

 

History

History
250 lines (202 loc) · 10.4 KB

AGENTS.md

File metadata and controls

250 lines (202 loc) · 10.4 KB

Project Memory: AgentSys

Cross-tool compatible: Works across all 5 platforms - Claude Code, OpenCode, Codex CLI, Cursor, and Kiro.

## Critical Rules (Priority Order)

  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 intel changes → checklists/repo-intel.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.
  1. 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.
  1. 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.
## 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

Pattern: Command → Agent → Skill (orchestration → invocation → implementation)

## 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-intel - Unified static analysis - git history, AST symbols, project metadata

Maintenance

  • /sync-docs - Update documentation to match code

Dev Commands

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 sync-lib         # Sync lib/ to plugins/
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 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

# Or invoke directly:
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 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
## Agents

35 agents across 15 plugins. Key agents by model:

Model Agents Use Case
opus exploration, planning, implementation, perf-orchestrator, debate-orchestrator, skillers-recommender Complex reasoning, analysis
sonnet task-discoverer, delivery-validator, ci-fixer, deslop-agent, reporters, learn, release-agent, skillers-compactor Validation, pattern matching
haiku worktree-manager, ci-monitor, simple-fixer Mechanical execution

See README.md and docs/reference/AGENTS.md for full agent list.

## Skills

32 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-intel

See README.md for full skill list.

## 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/
  • Cursor: .cursor/
  • Kiro: .kiro/
## 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
## 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
## Model Selection
Model When to Use
Opus Complex reasoning, analysis where imperfection compounds
Sonnet Validation, pattern matching, most agents
Haiku Mechanical execution, no judgment needed
## Core Priorities
  1. User DX (plugin users)
  2. Worry-free automation
  3. Token efficiency
  4. Quality output
  5. Simplicity
**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 - 5 platforms: Claude Code + OpenCode + Codex + Cursor + Kiro - ALL must work - Agent/Skill pattern: Agents invoke skills, skills have implementation - Create PRs for non-trivial changes