multi-agents-custom 2.0.0

package/README.md

@@ -0,0 +1,201 @@
+# multi-agents-custom
+
+Generates AI tool config files for a five-role software development pipeline —
+**PM → BA → Tech Lead → Developer → Tester** — directly into each tool's
+**native config folder**.
+
+No API calls. No runtime dependencies. Pure local file generation.
+
+Supported tools: **Cursor**, **GitHub Copilot**, **Qwen**, **Antigravity**
+
+---
+
+## What it does
+
+When installed (or run manually), the package writes persona instruction files
+into the correct directories for each AI tool so they pick them up natively:
+
+| Tool | Config folder | File format |
+|---|---|---|
+| Cursor | `.cursor/rules/` | `<role>.mdc` |
+| GitHub Copilot | `.github/prompts/` | `<role>.prompt.md` |
+| Qwen | `.qwen/` | `<role>.md` |
+| Antigravity | `.antigravity/` | `<role>.md` |
+
+Each file contains the system prompt for one of the five agent roles:
+
+| Role | Description |
+|---|---|
+| `pm` | Product Manager — extracts objectives, stakeholders & constraints |
+| `ba` | Business Analyst — writes user stories with acceptance criteria |
+| `techlead` | Tech Lead — designs architecture, tech stack & component map |
+| `developer` | Developer — produces implementation plans & code snippets |
+| `tester` | Tester — creates test strategy, test cases & tooling recommendations |
+
+---
+
+## Installation
+
+```bash
+npm install multi-agents-custom
+```
+
+Config files are generated automatically via the `postinstall` hook into the
+**project that installed the package** (`INIT_CWD`).
+
+To skip postinstall (e.g. in CI):
+
+```bash
+SKIP_MULTI_AGENTS_POSTINSTALL=1 npm install multi-agents-custom
+```
+
+---
+
+## Manual / CLI usage
+
+```bash
+# Generate for all tools (default)
+npx multi-agents-custom
+
+# Only generate for Cursor and Copilot
+npx multi-agents-custom --targets=cursor,copilot
+
+# Overwrite existing files
+npx multi-agents-custom --overwrite
+
+# Target a specific project root
+npx multi-agents-custom --root=/path/to/project
+
+# Suppress output
+npx multi-agents-custom --quiet
+
+# Help
+npx multi-agents-custom --help
+```
+
+---
+
+## Programmatic API
+
+```ts
+import { ConfigGenerator } from 'multi-agents-custom';
+
+const generator = new ConfigGenerator({
+  targets: 'all',          // 'cursor' | 'copilot' | 'qwen' | 'antigravity' | 'all'
+  projectRoot: '/my/app',  // default: process.cwd()
+  overwrite: false,        // skip files that already exist (default)
+  verbose: true,           // print progress (default)
+});
+
+const result = await generator.generate();
+// result.success  → boolean
+// result.written  → number of files created/overwritten
+// result.skipped  → number of files left untouched
+// result.errors   → number of write failures
+// result.files    → WriteResult[] with per-file status
+```
+
+### Custom prompts
+
+Override any agent's system prompt before generation:
+
+```ts
+const generator = new ConfigGenerator({
+  targets: ['cursor', 'copilot'],
+  agents: {
+    pm: {
+      systemPrompt: 'You are a domain-expert PM for fintech products. ...',
+    },
+    developer: {
+      systemPrompt: 'You are a Python/FastAPI expert. Always use Pydantic v2.',
+    },
+  },
+});
+
+await generator.generate();
+```
+
+### Low-level writer access
+
+```ts
+import { CursorWriter, DEFAULT_PERSONAS } from 'multi-agents-custom';
+
+const writer = new CursorWriter();
+const results = await writer.write(DEFAULT_PERSONAS, '/my/app', false);
+```
+
+---
+
+## Configuration reference
+
+### `GeneratorConfig`
+
+```ts
+interface GeneratorConfig {
+  /** Tool(s) to generate files for. Default: 'all' */
+  targets?: 'cursor' | 'copilot' | 'qwen' | 'antigravity' | 'all'
+           | ('cursor' | 'copilot' | 'qwen' | 'antigravity' | 'all')[];
+
+  /** Project root directory. Default: process.cwd() */
+  projectRoot?: string;
+
+  /** Per-role prompt / metadata overrides */
+  agents?: Partial<Record<'pm'|'ba'|'techlead'|'developer'|'tester', Partial<AgentPersona>>>;
+
+  /** Overwrite existing config files. Default: false */
+  overwrite?: boolean;
+
+  /** Print progress to stdout. Default: true */
+  verbose?: boolean;
+}
+```
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `SKIP_MULTI_AGENTS_POSTINSTALL` | `""` | Set to `"1"` to skip the postinstall hook |
+
+---
+
+## Project structure
+
+```
+src/
+├── agents/
+│   └── personas.ts          # Five default agent persona definitions
+├── cli/
+│   └── index.ts             # CLI entry point (postinstall + npx)
+├── generator/
+│   └── generator.ts         # ConfigGenerator orchestrator
+├── providers/
+│   ├── cursor.writer.ts     # Writes .cursor/rules/*.mdc
+│   ├── copilot.writer.ts    # Writes .github/prompts/*.prompt.md
+│   ├── qwen.writer.ts       # Writes .qwen/*.md
+│   ├── antigravity.writer.ts# Writes .antigravity/*.md
+│   └── factory.ts           # resolveWriters() factory
+├── types/
+│   └── index.ts             # All TypeScript types
+├── utils/
+│   ├── fs.ts                # File-system helpers
+│   └── logger.ts            # Coloured console logger
+└── index.ts                 # Public API entry point
+```
+
+---
+
+## Scripts
+
+```bash
+npm run build      # Compile to dist/
+npm run dev        # Watch mode build
+npm test           # Run unit tests
+npm run typecheck  # TypeScript type check
+npm run lint       # ESLint
+```
+
+---
+
+## License