skills/proffesor-for-testing__agentic-qe

mirror of https://github.com/proffesor-for-testing/agentic-qe.git synced 2026-09-19 08:45:47 +08:00

Files

T

Profa c0d469a3bb fix: clean up stale v3/ references and protect memory namespaces post-flatten

Brutal honesty review of the flatten-to-root migration found 12 categories
of issues. This commit fixes all of them:

- Fix @agentic-qe/v3 package refs in init installers and quality-criteria-service
- Fix 7 broken import() paths in rvf-baseline-benchmark.ts (v3/src → src)
- Fix prepare-assets.sh and demo-warmup.sh path references
- Delete dead scripts/migrate-v2-to-v3-memory.js
- Remove .claude-flow daemon state dirs (284KB) from agents/skills
- Add .claude-flow exclusion to .npmignore
- Fix JSDoc @agentic-qe/v3/ → agentic-qe/ in 27 source files
- Fix @module v3/ tags in 9 dream engine files
- Fix stale v3/ path refs in docs and architecture ADRs
- Revert memory namespace changes (aqe/v3/domains/* are DB identifiers,
  not filesystem paths — changing them orphans 150K+ existing records)
- Update CLAUDE.md with agent classification rules (QE vs non-QE agents)
- Fix domain-team-manager test (scaling is not capped by defaultTeamSize)
- Fix adr-040 timing test threshold (20ms → 50ms for CI tolerance)
- Rename test:v3 → test:all in package.json
- Update README.md project structure tree
- Fix infra-healing test and demo script cd v3 references

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-01 12:27:44 +00:00

3.8 KiB

Raw Permalink Blame History

Agentic QE Package Publishing Structure

This document explains how the agentic-qe package is structured and published to npm.

Package Structure

agentic-qe/
├── package.json          # ROOT - This is what gets published to npm
├── v3/                   # v3 implementation (DDD architecture)
│   ├── package.json      # v3-specific deps (NOT published directly)
│   ├── dist/             # Built CLI, MCP server, and library
│   │   ├── cli/bundle.js # CLI entry point
│   │   ├── mcp/bundle.js # MCP server entry point
│   │   └── index.js      # Library entry point
│   └── assets/           # Agent definitions, skills, etc.
└── .claude/              # Claude Code integration files
    ├── agents/           # Agent definitions
    ├── skills/           # Skills
    └── commands/         # Commands

Which package.json is Published?

The ROOT package.json is what npm publishes.

The files array in root package.json specifies what gets included:

{
  "files": [
    "v3/dist/**",
    "v3/assets/**",
    "v3/package.json",
    ".claude/agents",
    ".claude/skills",
    ".claude/commands",
    ".claude/helpers",
    "README.md",
    "CHANGELOG.md",
    "LICENSE"
  ]
}

Important: Dependencies

All runtime dependencies must be in ROOT package.json's dependencies, not:

NOT in root devDependencies (users don't get these)
NOT only in v3/package.json (this file is included but its deps aren't auto-installed)

Common Pitfall: Missing Dependencies

If the CLI fails with Cannot find package 'X', check:

Is X in root package.json dependencies?
If not, add it there (not just in v3/package.json)

Example error:

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'typescript'

Solution: Add typescript to root package.json dependencies.

Build Process

npm run build → runs TypeScript compilation + esbuild bundles
Build outputs:
- TypeScript compilation → dist/
- CLI bundle (esbuild) → dist/cli/bundle.js
- MCP bundle (esbuild) → dist/mcp/bundle.js

Publishing Workflow

Update version in root package.json
Create GitHub release with tag (e.g., v3.1.1)
GitHub Action npm-publish.yml triggers:
- Installs deps from root
- Builds v3
- Runs tests
- Publishes to npm

Versioning

Root package.json version is the published version
v3/package.json version should match but is NOT what npm reads
Always update root version when releasing

Entry Points

{
  "main": "./v3/dist/index.js",      // Library import
  "types": "./v3/dist/index.d.ts",   // TypeScript types
  "bin": {
    "aqe": "./v3/dist/cli/bundle.js",       // CLI
    "aqe-mcp": "./v3/dist/mcp/bundle.js"    // MCP server
  }
}

Checklist Before Publishing

Root package.json version is updated
All runtime imports are in root dependencies (not devDependencies)
v3 builds successfully: npm run build
Tests pass: npm test
CLI works locally: node v3/dist/cli/bundle.js --version

Troubleshooting

"Cannot find package 'X'" after install

The package X is imported at runtime but not in root dependencies.

Fix: Add to root package.json dependencies:

{
  "dependencies": {
    "X": "^version"
  }
}

"Module not found" for v3 internal imports

The esbuild bundle may have incorrect externals. Check:

v3/scripts/build-cli.js - externals list
v3/scripts/build-mcp.js - externals list

Version mismatch

Ensure both are in sync:

Root package.json version (this is what npm uses)
v3/package.json version (for internal consistency)

3.8 KiB Raw Permalink Blame History