Skip to content

AGENTS.md

Latest commit

 

History

History
110 lines (89 loc) · 4.07 KB

AGENTS.md

File metadata and controls

110 lines (89 loc) · 4.07 KB
Raw

Agentic QE Contributor Instructions

Scope

These instructions apply to the entire repository. A more deeply nested AGENTS.md may add or override instructions for its subtree.

Agentic QE is a TypeScript/Node.js quality-engineering platform. Product code lives in src/, tests in tests/, scripts in scripts/, documentation in docs/, and configuration in config/.

Safety and Data Protection

  • Never commit secrets, credentials, .env files, or generated sensitive data.
  • Treat .agentic-qe/memory.db and every learning database as production data.
  • Never overwrite, recreate, delete, consolidate, or migrate a database without explicit user approval.
  • Test database fixes against a copy. Before an approved database operation, create a timestamped backup; afterward, verify SQLite integrity and relevant row counts.
  • Do not modify production adapters or published-package behavior beyond the user-approved scope. Explain material production impact before applying a high-risk change.

Project Boundaries

  • Keep source changes in src/, tests in tests/, utilities in scripts/, docs in docs/, and configuration in config/ unless an existing project convention requires another location.
  • Follow the existing domain-driven bounded contexts and event-based state patterns.
  • Use typed interfaces for public APIs and validate input at system boundaries.
  • Prefer focused files under 500 lines.
  • Do not add ruflo as a runtime dependency or call its CLI/MCP from shipped product code. It is development-time coordination tooling only.

AQE Agents and Skills

  • Distinguish AQE/QE assets from Claude Flow platform assets.
  • Shipped QE agents are .claude/agents/v3/qe-*.md. Non-qe- definitions in that directory are project or platform agents and are not part of the shipped AQE fleet.
  • assets/agents/v3/ must contain only shipped qe-*.md agents.
  • AQE skills live under .claude/skills/, excluding platform infrastructure families such as v3-*, flow-nexus-*, agentdb-*, reasoningbank-*, and swarm-*, unless the task explicitly targets platform skills.
  • Preserve memory namespace strings such as aqe/v3/domains/*; they are database identifiers, not filesystem paths.
  • After changing shipped agents or skills, run the relevant parity and sync checks described below.

Implementation Workflow

  • Read a file before editing it and preserve unrelated user changes.
  • For bugs, reproduce the reported behavior before patching and search the repository for every instance of the faulty pattern.
  • Prefer London-school, mock-first TDD for new behavior when it fits the surrounding tests.
  • Add or update focused tests for behavior changes.
  • CLI and MCP paths can diverge. A change affecting one must be checked against the other when the same capability is exposed through both.
  • Never claim a fix or migration succeeded without reporting the actual verification command and result.

Commands

Use the narrowest relevant checks first:

npm run typecheck
npm run lint
npm run test:unit:fast
npm run test:unit:mcp
npm run test:integration:fast

For full validation when the scope warrants it:

npm run build
npm run test:ci
npm run verify:invariants
npm run verify:skill-parity
npm run verify:conservation
npm run sync:agents:check

Agent/skill-specific checks:

npm run verify:agent-skills
npm run verify:counts
npm run skills:validate-tier3

Browser and PostgreSQL integration tests require their documented external services and should be run only when relevant.

Release and Git Rules

  • Use Conventional Commits when the user asks for a commit.
  • Do not commit, push, publish, tag, create a release, or alter a pull request unless the user explicitly requests it.
  • Treat package.json as the package-version source of truth, but search for all hard-coded versions before a version change.
  • Production releases are created from merged main through .github/workflows/npm-publish.yml; never publish production packages locally.
  • Keep pull-request descriptions outcome-focused and include verification evidence.