Refactor AGENTS.md to point to detailed docs and shorten package.json description

Author: donnes

AGENTS.md

@@ -1,182 +1,20 @@
 # AGENTS.md
 
-This repository is a Node.js/Bun TypeScript CLI for managing AI agent configurations.
-It provides an adapter-based architecture to sync configs for Claude Code, Cursor,
-Windsurf, OpenCode, and VSCode across machines using git and symlinks/copies.
-
-## Quick facts
-- Runtime: Node.js ≥20 or Bun
-- Language: TypeScript (ES modules)
-- Entry point: src/index.ts (shebang: `#!/usr/bin/env node`)
-- Build: tsup (outputs to dist/)
-- OS targets: macOS + Linux (Windows planned)
-- Package manager: npm or bun
-- Package name: @donnes/syncode
-
-## Commands (build / lint / test)
-- Install dependencies: `bun install` or `npm install`
-- Run CLI in dev mode: `bun run dev` (uses tsx)
-- Build for production: `bun run build` (uses tsup)
-- Type check: `bun run typecheck`
-- Link the CLI globally: `bun link` or `npm link`
-- CLI usage help: `syncode help`
-
-Notes
-- There is no lint script defined in `package.json`.
-- There is no test runner configured in this repo.
-- Build outputs to `dist/` directory via tsup.
-
-## Single-test guidance
-- No test framework is configured, so there is no "single test" command.
-- If you add tests, also add a `package.json` script and document the single-test
-  usage here.
-
-## Repository structure
-- `src/index.ts` is the CLI entry and interactive menu.
-- `src/commands/` contains 3 user-facing commands: new, sync, status
-- `src/adapters/` contains agent adapters implementing AgentAdapter interface
-- `src/config/` contains configuration management (manager.ts, types.ts)
-- `src/utils/` contains shared helpers (fs/git/paths/shell/platform).
-- `configs/` (in user's repo) stores tracked agent configs
-
-## Architecture
-
-### Adapter System
-The project uses an adapter-based architecture where each AI agent has its own adapter:
-- **AgentAdapter interface** (`src/adapters/types.ts`) - defines the contract
-- **Built-in adapters** - claude, cursor, windsurf, opencode, vscode
-- **AdapterRegistry** (`src/adapters/registry.ts`) - central registry for all adapters
-- Each adapter handles platform-specific paths, import/export, and sync strategies
-
-### Sync Strategies
-- **Symlink** (default): Live sync, changes reflected immediately
-- **Copy**: One-way copy (used for Claude to preserve cache/history)
-- Configured per adapter in `syncStrategy.import` and `syncStrategy.export`
-
-### Configuration
-- Global config stored at `~/.syncode/config.json`
-- User's agent configs stored in their chosen repo (e.g., `~/agent-configs`)
-- Each adapter determines its own system paths per platform
-
-## Code style guidelines
-
-### Formatting
-- Use double quotes for strings.
-- Use semicolons.
-- Use trailing commas in object/array literals.
-- One statement per line; avoid clever one-liners.
-- Keep functions small and single-purpose.
-- Favor explicit spacing for readability.
-
-### Imports
-- Use ES module syntax (import/export, not require).
-- Order: external packages first, then relative imports.
-- Use `import type` for types when possible.
-- Prefer named imports; use `import * as p` for @clack/prompts.
-
-### Types and interfaces
-- Prefer interfaces for shared shapes (see `src/adapters/types.ts`).
-- Keep union types narrow and explicit (e.g. Platform: "macos" | "linux" | "windows").
-- Use `Record<string, T>` for indexed dictionaries.
-- Avoid `any`; if unavoidable, keep it local and explain with context.
-- Keep result types consistent (`success`, `message`, optional fields).
-
-### Naming conventions
-- File names are lowercase with dashes only when needed.
-- Functions are `camelCase`.
-- Classes/Interfaces are `PascalCase` (e.g. `AgentAdapter`, `AdapterRegistry`).
-- Constants are `SCREAMING_SNAKE_CASE` only for true constants (e.g. `SUPPORTED_AGENTS`).
-- Adapter IDs are lowercase (e.g. "claude", "cursor", "opencode").
-
-### Error handling
-- Use `try/catch` around filesystem and shell operations.
-- Return structured results (success + message) rather than throwing.
-- When catching, surface a clear message for the CLI user.
-- In CLI flows, cancel early on prompt cancellations.
-
-### Async / sync usage
-- Use async/await for shell calls and long-running operations.
-- Synchronous fs calls are acceptable for small, controlled operations.
-- Keep CLI output responsive; use spinners for long operations.
-
-### CLI UX
-- Use @clack/prompts for interactive flows.
-- Always handle cancellations with `p.isCancel`.
-- Use `p.intro` / `p.outro` for command boundaries.
-- Keep status output short and scannable.
-
-### Filesystem operations
-- Use helpers from `src/utils/fs.ts` when available.
-- Always ensure parent directories exist before writing.
-- Respect symlink behavior: avoid overwriting without backups.
-- For config exports, back up existing paths when not symlinked.
-
-### Git operations
-- Use helpers from `src/utils/git.ts`.
-- Prefer `git -C` with `REPO_ROOT`.
-- Keep git output minimal and user-friendly.
-
-### Paths
-- Use `systemPaths` and `repoPaths` from `src/utils/paths.ts`.
-- Prefer `contractHome` for user-facing paths.
-- Avoid hardcoding OS-specific locations.
-
-## Adding new commands
-- Place new command files in `src/commands/`.
-- Export a single `*Command` function (async, no parameters).
-- Import and register in `src/index.ts` in the `commands` object.
-- Add to the interactive menu options in the `p.select` call.
-- Add to `showHelp()` function for CLI help output.
-
-## Adding new agent adapters
-- Implement `AgentAdapter` interface from `src/adapters/types.ts`.
-- Create new file in `src/adapters/` (e.g., `newagentagent.ts`).
-- Export adapter instance (e.g., `export const newAgentAdapter: AgentAdapter`).
-- Import and register in `src/adapters/registry.ts` in `registerBuiltinAdapters()`.
-- Add agent ID to `SUPPORTED_AGENTS` in `src/config/types.ts`.
-- Define sync strategy (symlink or copy) in adapter definition.
-- Implement platform-specific path resolution in `getConfigPath()`.
-- Keep import/export logic symmetric and idempotent.
-
-## Agent adapter behavior
-- **Import**: Copy files from system to repo (preserves originals).
-- **Export**: Create symlink from system to repo OR copy from repo to system.
-- **Backup**: Always backup existing system configs before export.
-- Avoid destructive operations without user confirmation.
-
-## CLI Commands
-
-### `syncode new`
-- Initialize a new agent config repository
-- Auto-detects installed AI agents
-- Prompts for repo path, GitHub remote, agent selection
-- Creates directory structure and initial git commit
-- Imports existing configs from system
-- Creates global config at `~/.syncode/config.json`
-
-### `syncode sync`
-- Sync agent configs between system and repo
-- Prompts for direction: import (system → repo) or export (repo → system)
-- Import: copies configs from system to repo
-- Export: creates symlinks (or copies for Claude) from system to repo
-- Automatic backups before destructive operations
-
-### `syncode status`
-- Show status of synced agents
-- Lists enabled/detected agents
-- Shows sync method (symlink vs copy)
-- Shows git status of repo
-
-## Common pitfalls
-- Do not use `require()` - this is an ES module project, use `import` instead.
-- Do not assume a test runner exists.
-- Do not add new scripts without updating this doc.
-- Do not add emoji output unless already used in command output.
-- Remember that adapters are registered at module load time (see registry.ts).
-- Always use platform detection for path resolution (don't hardcode paths).
-
-## When editing AGENTS.md
-- Keep it under 200 lines to stay readable.
-- Update command sections as scripts or commands change.
-- Document any new adapters immediately.
-- Document any new lint/test tools immediately.
+Syncode is a Node.js/Bun TypeScript CLI that syncs AI agent configurations via adapter-based git + symlink/copy workflows.
+
+## Essentials
+- Runtime: Node.js >=20
+- Package manager: npm (bun supported)
+- Non-standard commands:
+  - `bun run dev`
+  - `bun run build`
+  - `bun run typecheck`
+
+## More details
+- `docs/agents/commands.md`
+- `docs/agents/project-structure.md`
+- `docs/agents/architecture.md`
+- `docs/agents/code-style.md`
+- `docs/agents/feature-development.md`
+- `docs/agents/troubleshooting.md`
+- `docs/agents/roadmap.md`

docs/agents/architecture.md

@@ -0,0 +1,27 @@
+# Architecture and Sync Logic
+
+## Adapter system
+- Each agent has an adapter in `src/adapters/` registered in `registry.ts`.
+
+## Sync strategies
+- `symlink` (default): Live sync between system and repo.
+- `copy`: One-way copy (used for Claude to preserve cache).
+
+## Global config
+- `~/.syncode/config.json` tracks the repository location.
+
+## Core interface: `AgentAdapter`
+- `id`: Unique lowercase identifier.
+- `getConfigPath(platform)`: Resolves the system path for the agent's config.
+- `getRepoPath(repoRoot)`: Determines where the config is stored in the sync repository.
+- `import(system, repo)`: Logic to bring configs into the repository.
+- `export(repo, system)`: Logic to apply configs to the system.
+- `isInstalled(platform)`: Detection logic for the agent.
+
+## How to add a new adapter
+
+1. Create `src/adapters/<name>.ts` implementing `AgentAdapter`
+2. Export the adapter in `src/adapters/index.ts`
+3. Register it in `src/registry.ts`
+4. Add platform detection in `src/platforms/` if needed
+5. Test with `syncode status` to verify detection

docs/agents/code-style.md

@@ -0,0 +1,28 @@
+# Code Style Guidelines
+
+## Formatting and imports
+- Use double quotes for strings and semicolons for statements.
+- Use trailing commas in object/array literals.
+- Use ES module syntax (`import`/`export`). No `require()`.
+- Order: external packages first, then relative imports.
+- Use `import type` for type-only imports.
+- Prefer named imports; use `import * as p` for `@clack/prompts`.
+
+## Casing and naming
+- File names: lowercase with dashes (e.g., `agent-adapter.ts`).
+- Functions/variables: `camelCase`.
+- Classes/interfaces: `PascalCase`.
+- Constants: `SCREAMING_SNAKE_CASE` (only for true constants).
+- Adapter IDs: lowercase (e.g., "claude").
+
+## Types and error handling
+- Prefer interfaces for shared shapes. Use JSDoc for public fields.
+- Avoid `any`. Use `unknown` if necessary with type guards.
+- Return structured results (`{ success: boolean, message: string }`) instead of throwing when possible in CLI flows.
+- Use `try/catch` around filesystem and shell operations.
+
+## Async and filesystem
+- Use `async`/`await` for shell calls and long-running operations.
+- Use helpers from `src/utils/fs.ts` and `src/utils/git.ts`.
+- Always ensure parent directories exist before writing.
+- Respect symlinks: avoid overwriting without backups.

docs/agents/commands.md

@@ -0,0 +1,55 @@
+# Commands
+
+## Tooling
+- Install dependencies: `bun install` or `npm install`
+- Run CLI in dev mode: `bun run dev` (uses tsx)
+- Build for production: `bun run build` (uses tsup)
+- Type check: `bun run typecheck` (uses `tsc --noEmit`)
+- Link CLI globally: `bun link` or `npm link`
+- CLI usage help: `syncode help`
+
+## Release/build checklist
+
+- [ ] Update version in `package.json`
+- [ ] Run `bun run build` to verify production build
+- [ ] Run `bun run typecheck` to verify types
+- [ ] Test CLI locally: `bun link && syncode status`
+- [ ] Create git tag: `git tag v<x.y.z>`
+- [ ] Push tag: `git push --tags`
+- [ ] Publish to npm (if applicable): `npm publish`
+
+## Notes
+- No lint script or test runner currently configured.
+- No single-test command available yet. If you add tests, document them here.
+
+## CLI commands
+
+### `syncode new`
+- Purpose: Initializes a new agent configuration repository.
+- Actions:
+  - Detects installed AI agents on the current system.
+  - Prompts for a local repository path and an optional GitHub remote.
+  - Creates the directory structure, `.gitignore`, and an initial git commit.
+  - Imports existing configurations from system paths to the repository.
+  - Persists global settings in `~/.syncode/config.json`.
+
+### `syncode sync`
+- Purpose: Synchronizes agent configurations between the system and the repository.
+- Modes:
+  - Import (System -> Repo): Copies local configuration files into the repository.
+  - Export (Repo -> System): Applies repository configurations to the system.
+- Safety: Automatically creates backups of existing system configurations.
+
+### `syncode status`
+- Purpose: Displays the current synchronization state.
+- Output:
+  - List of detected and enabled agents.
+  - Active sync method for each agent (symlink vs. copy).
+  - Current git status of the configuration repository.
+
+### `syncode push`
+- Purpose: Commits and pushes changes to the remote repository.
+- Actions:
+  - Stages all changes in the configuration directory.
+  - Prompts for a commit message.
+  - Executes `git push` to the configured remote.

docs/agents/feature-development.md

@@ -0,0 +1,10 @@
+# Feature Development
+
+## New agent adapters
+1. Implement `AgentAdapter` in `src/adapters/types.ts`.
+2. Register in `src/adapters/registry.ts`.
+3. Define platform-specific path resolution in `getConfigPath()`.
+
+## New commands
+1. Place in `src/commands/` and export a single async function.
+2. Register in `src/index.ts` in the `commands` object and `showHelp()`.

docs/agents/project-structure.md

@@ -0,0 +1,9 @@
+# Project Structure
+
+- Entry point: `src/index.ts` (shebang: `#!/usr/bin/env node`)
+- Build output: `dist/`
+- `src/commands/`: User-facing commands (new, sync, status, push).
+- `src/adapters/`: Agent adapters implementing `AgentAdapter`.
+- `src/config/`: Configuration management (manager.ts, types.ts).
+- `src/utils/`: Shared helpers (fs, git, paths, shell, platform).
+- `configs/`: In the user's repo, stores tracked agent configs.

docs/agents/roadmap.md

@@ -0,0 +1,6 @@
+# Future Roadmap
+
+- Windows support (path resolution and symlink handling).
+- Canonical skill format implementation (Phase 4).
+- Automatic periodic background sync.
+- Support for more editors/agents.

docs/agents/troubleshooting.md

@@ -0,0 +1,6 @@
+# Common Pitfalls and Troubleshooting
+
+- Missing agents: If an agent is not detected, check `getConfigPath()` in its adapter.
+- Permission errors: Filesystem operations (symlinks) may require specific permissions.
+- Symlink conflicts: If a file exists where a symlink should be, the CLI prompts for backup/overwrite.
+- Claude history: Claude Code uses the `copy` strategy because local sqlite databases do not behave well with symlinks.

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@donnes/syncode",
   "version": "1.0.0",
-  "description": "Agent Configuration Manager - Sync AI code agent configs (Claude Code, Cursor, Windsurf, OpenCode) across machines and projects.",
+  "description": "Sync AI code agent configs (Claude Code, Cursor, Windsurf, OpenCode) across machines and projects.",
   "private": false,
   "type": "module",
   "bin": {