Skip to content

AGENTS.md

Latest commit

 

History

History
155 lines (110 loc) · 7.63 KB

AGENTS.md

File metadata and controls

155 lines (110 loc) · 7.63 KB

CLAUDE.md & AGENTS.md

Guidance for any AI agent working in this repository. CLAUDE.md is a symlink to this file.

What this repo is

A pnpm workspace monorepo hosting AI agent plugins developed at Unic. Today it contains Claude Code plugins; the structure supports plugins for other agents (GitHub Copilot, etc.) in the future.

Workspace layout

apps/
├── claude-code/              # Claude Code plugins — one dir per plugin
│   ├── pr-review/
│   ├── auto-format/
│   ├── unic-confluence/
│   ├── unic-archon-dlc/
│   └── unic-pr-review/
└── copilot/                  # GitHub Copilot plugins (future)
packages/
├── biome-config/             # @unic/biome-config
├── tsconfig/                 # @unic/tsconfig
└── release-tools/            # @unic/release-tools (bump / sync-version / tag / verify-changelog)
docs/
├── adr/                      # Architectural Decision Records
├── agents/                   # Agent skill documentation
├── inbox/                    # Retired idea-capture notes (historical)
├── issues/                   # Grilled and scoped feature issues
├── plans/                    # Retired spec files (historical)
├── process/                  # Process and workflow guides
└── research/                 # Research notes and explorations

Navigation

  • Plugin manifests: apps/<agent>/<plugin>/.claude-plugin/plugin.json and marketplace.json
  • Shared release scripts: packages/release-tools/scripts/
  • Architectural decisions: docs/adr/
  • Process templates: docs/process/

Commands

pnpm install                            # install all workspace deps
pnpm check                              # Biome + Prettier check (whole tree)
pnpm format                             # Biome + Prettier fix (whole tree)
pnpm ci:check                           # same as check, non-interactive (for CI)
pnpm test                               # run tests across all packages
pnpm typecheck                          # type-check across all packages

# Per-plugin operations
pnpm --filter <name> bump patch         # bump plugin version
pnpm --filter <name> verify:changelog   # check changelog

Tech stack

  • Runtime: Node.js ≥ 22. .nvmrc is the source of truth for local dev (currently 24.15.0) and is consumed by actions/setup-node in CI.
  • Package manager: pnpm 10 (workspace mode, catalog pinning)
  • Module system: ESM ("type": "module") throughout
  • Linter/formatter: Biome 2 for code/JSON; Prettier for Markdown only
  • Type checking: tsc --checkJs --noEmit on .mjs files; no compilation step
  • Test runner: node:test built-in

Cross-platform requirement

Every plugin must work on macOS, Windows, and Linux. Use Node.js APIs (node:path, node:fs, node:os) instead of shell commands. CI runs all three OSes × Node 22 and 24.

Code conventions

  • Tabs for indentation in .mjs/.js/.ts files; spaces (2) for .json/.yml/.yaml
  • Single quotes, no semicolons, trailing commas ES5-style (enforced by Biome)
  • Line width 120 (Biome)
  • Prettier for Markdown only
  • No TypeScript compilation — // @ts-check + JSDoc for type safety

Versioning

Plugins are versioned independently. plugin.json is the source of truth. Use pnpm --filter <name> bump <patch|minor|major> — never hand-edit marketplace.json.

Tag scheme: <plugin-name>@<version> (e.g. auto-format@0.5.5).

Conventional commits

Use package scope: feat(auto-format): …, fix(pr-review): …, chore(release-tools): …, chore(unic-archon-dlc): …, feat(unic-pr-review): ….

Git branching (Gitflow)

Branch Purpose
main Production. Only receives merge commits from develop (or hotfix/*). The release workflow fires here and creates tags.
develop Integration. Default target for all feature PRs. CI runs on every push and PR.
feature/<name> Day-to-day work. Branch from develop, PR back to develop.
hotfix/<name> Urgent fixes only. Branch from main, PR to both main and develop.

Never commit directly to main or develop. Always go through a PR.

Release flow

To ship a new plugin version:

  1. On a feature branch, bump the version: pnpm --filter <name> bump <patch|minor|major>
  2. Add a dated entry to the plugin's CHANGELOG.md under the new version.
  3. Open a PR targeting develop. CI runs verify:changelog on all PRs — it will fail if the changelog entry is missing or malformed.
  4. After the PR merges to develop, open a release PR from develop → main.
  5. After the release PR merges, the release workflow on main detects that <name>@<version> has no tag yet and creates it automatically.

CI summary:

Event Root checks Package tests verify:changelog
PR (any branch) ✓ ✓ (changed packages) ✓
Push to develop ✓ ✓ (changed packages) —
Push to main ✓ ✓ (changed packages) —

Feature-driven development

New work enters through the issue tracker as Features. Use /tdd to implement individual issues, or unic-dlc-build (via unic-archon-dlc) once the harness is set up in this repo.

Do not add

  • External runtime deps to plugins unless truly essential (auto-format has zero; that's the bar)
  • Turborepo or other build orchestrators — plain pnpm workspaces is the current choice
  • Features not tracked in the issue tracker — open a Feature first
  • Per-plugin pnpm-lock.yaml files — the root lockfile is canonical; sub-package lockfiles should never be committed

LICENSE files

Never create, copy, or delete LICENSE files. The maintainer manages these manually in every package and plugin directory. If an acceptance criterion requires a LICENSE file to exist, warn the maintainer to add it themselves before continuing.

Skill summary

Issue tracker

Issues live in GitHub Issues at unic/unic-agents-plugins (planned migration to Azure DevOps). See docs/agents/issue-tracker.md.

Triage labels

8-state vocabulary: needs-triage → needs-info → needs-specs → ready-for-agent / ready-for-human → resolved → closed (or rejected). See docs/agents/triage-labels.md.

Domain docs

Multi-context repo: Per-plugin CONTEXT.md files live under apps/claude-code/<plugin>/. Root CONTEXT-MAP.md at repo root. See docs/agents/domain.md.

Agent skills

  • issue-tracker.md — issue tracker backend, CLI, create/update conventions
  • labels.md — three-tier label taxonomy: state, type, priority
  • branching.md — branching strategy, branch names, PR targets
  • domain.md — single-context vs multi-context, CONTEXT.md and ADR locations
  • workflow.md — seven workflow phases, artifact outputs, docs/workflow/ paths