@2amtech/hai 0.0.1 → 0.0.2

package/README.md

@@ -1,197 +1,174 @@
-# hai-cli
+# @2amtech/hai
 
-A TypeScript CLI that bridges ticket management, specification systems, and AI tools. hai syncs tickets and specs from platforms like Jira and Confluence to a local `.ai/` directory and exposes them via an [MCP](https://modelcontextprotocol.io/) server so AI coding assistants can access project context natively.
+**Helper AI (HAI)** is an npm CLI that sets up a standardized AI-assisted development workflow for your project. It syncs tickets and specs from platforms like Jira and Confluence into a local (git ignored) `.ai/` directory and exposes an MCP server to your AI, and installs purpose-built prompts and subagents into your AI coding environment — so your AI assistant can plan, research, and implement work with full project context and easily pull tickets and specification in AI readable MD files.
 
-## Features
+## Installation
 
--   **Ticket sync** — pull active and completed tickets from Jira (or other providers) into `.ai/tickets/`
--   **Spec sync** — pull Confluence pages (or other sources) into `.ai/specs/`
--   **MCP server** — expose tickets and specs as tools over stdio for AI assistants like Claude Code and GitHub Copilot
--   **Plugin architecture** — add new integrations without touching core code
--   **Interactive setup** — guided wizard for first-time configuration
+```bash
+npm install -g @2amtech/hai
+```
 
 ## Quick start
 
 ```bash
-# Install dependencies
-npm install
+hai init     # Interactive wizard — pick your AI provider, ticket source, and spec source
+hai pull     # Sync tickets and specs to .ai/
+```
 
-npm run install-cli # Installs hai globally
+That's it. Your AI assistant now has access to your project's tickets, specs, prompts, and agents.
 
-hai init
+MCP server will automatically be added for your provider. If you need add mcp server manually you can add it as:
+
+```bash
+hai mcp .
 ```
 
 ## Commands
 
-| Command         | Description                                               |
-| --------------- | --------------------------------------------------------- |
-| `hai init`      | Interactive setup wizard — select plugins, enter creds    |
-| `hai configure` | Update existing credentials and settings                  |
-| `hai pull`      | Sync tickets and specs to the `.ai/` directory            |
-| `hai status`    | Show current contents of `.ai/`                           |
-| `hai get <KEY>` | Fetch a specific ticket (`--recursive` for linked issues) |
-| `hai mcp`       | Start MCP server over stdio                               |
+| Command         | Description                                                    |
+| --------------- | -------------------------------------------------------------- |
+| `hai init`      | Interactive setup wizard — select providers, enter credentials |
+| `hai pull`      | Sync tickets and specs to `.ai/`                               |
+| `hai status`    | Show sync status (ticket counts, last sync time)               |
+| `hai get <KEY>` | Fetch a specific ticket (e.g. `PROJ-123`)                      |
+| `hai mcp [dir]` | Start the MCP server over stdio                                |
 
-## Project structure
+### Flags
 
-```
-source/
-├── cli.tsx              # Entry point (meow CLI setup)
-├── app.tsx              # Command router
-├── types.ts             # Core domain types (Ticket, SpecPage, providers)
-├── commands/            # Command implementations
-│   ├── init.tsx         # hai init
-│   ├── configure.tsx    # hai configure
-│   ├── pull.tsx         # hai pull
-│   ├── status.tsx       # hai status
-│   ├── get.tsx          # hai get
-│   └── mcp/             # MCP server (runs outside Ink, raw stdio)
-├── plugins/             # Plugin system
-│   ├── types.ts         # HaiPlugin interface
-│   ├── registry.ts      # Plugin registration and lookup
-│   ├── resolve.ts       # Provider resolution from config
-│   ├── atlassian/       # Jira + Confluence provider
-│   ├── claude-code/     # Claude Code AI provider
-│   ├── vscode-copilot/  # GitHub Copilot AI provider
-│   ├── local/           # Local provider
-│   ├── none/            # No-op provider
-│   └── other-ai/        # Generic AI provider
-├── wizard/              # Wizard step components
-├── ui/                  # Reusable UI components (select, text-input, spinner)
-├── components/          # Business logic (sync-engine, spec-engine)
-├── hooks/               # React hooks (use-config, use-async)
-├── helpers/             # Utilities (config I/O, preflight checks, fs helpers)
-└── schemas/             # Zod config schema
-```
+| Flag                | Commands | Description                           |
+| ------------------- | -------- | ------------------------------------- |
+| `--tickets`, `-t`   | `pull`   | Sync tickets only                     |
+| `--specs`, `-s`     | `pull`   | Sync specs only                       |
+| `--dry-run`         | `pull`   | Preview changes without writing       |
+| `--update-local`    | `pull`   | Remove local files not found remotely |
+| `--recursive`, `-r` | `get`    | Also fetch linked issues              |
 
-## Development
+## Supported AI providers
 
-### Prerequisites
+HAI integrates with the following AI coding environments:
 
--   Node.js >= 16
--   npm
+| Provider           | ID               | MCP config location | Prompts installed to | Agents installed to |
+| ------------------ | ---------------- | ------------------- | -------------------- | ------------------- |
+| **Claude Code**    | `claude-code`    | `.mcp.json`         | `.claude/commands/`  | `.claude/agents/`   |
+| **GitHub Copilot** | `vscode-copilot` | `.vscode/mcp.json`  | `.github/prompts/`   | `.github/agents/`   |
+| **Cursor**         | `cursor`         | `.cursor/mcp.json`  | `.cursor/commands/`  | `.cursor/agents/`   |
+| **Other**          | `other`          | _(manual setup)_    | `.ai/prompts/`       | `.ai/agents/`       |
 
-### Build and run
+All providers register the HAI MCP server and install the full set of prompts and agents into the appropriate directories for that environment.
 
-```bash
-npm run build       # Compile TypeScript to dist/
-npm run dev         # Watch mode — recompiles on change
-npm run cli         # Build and run in one step
-npm test            # Run Prettier check + XO lint + AVA tests
-npm run format      # Auto-format with Prettier
-```
+## Supported ticket and spec providers
 
-### Tech stack
+| Provider      | ID          | Capabilities    | Description                            |
+| ------------- | ----------- | --------------- | -------------------------------------- |
+| **Atlassian** | `atlassian` | Tickets + Specs | Jira for tickets, Confluence for specs |
+| **Local**     | `local`     | Tickets + Specs | Read from local filesystem directories |
+| **None**      | `none`      | Tickets + Specs | Disabled / no-op provider              |
 
--   **TypeScript 5** — strict mode, ESM-only (`"type": "module"`)
--   **Ink 4** — React 18 for terminal UIs
--   **Meow** — CLI argument parsing
--   **Zod 4** — runtime config validation
+### Atlassian provider
 
-### Code conventions
+- **Jira**: Fetches active and done tickets by project, supports recursive linked-issue fetching, custom fields, and comments
+- **Confluence**: Fetches pages by space (optionally scoped to an ancestor page), converts Atlassian Document Format (ADF) to Markdown, and preserves page hierarchy
 
--   **Indentation**: tabs (see `.editorconfig`)
--   **Imports**: use `.js` extensions in all relative imports (ESM requirement)
--   **Types**: use the `type` keyword for type-only imports (`import type {Foo} from ...`)
--   **Props**: define inline with `type Props = { ... }` — no `interface`, no `prop-types`
--   **Components**: default exports for page-level, named exports for UI components
--   **Formatting**: Prettier via `@vdemedes/prettier-config` (tabs, single quotes, trailing commas)
+## Prompts
 
-## Adding a plugin
+HAI ships with 7 built-in prompts that are installed into your AI editor as commands:
 
-Plugins let you integrate new ticket sources, spec providers, or AI tools. Each plugin implements the `HaiPlugin` interface.
+| Prompt             | Description                                                                                                            |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| **implement**      | Full implementation workflow — fetches tickets, researches context, plans, and spawns dev agents in parallel by domain |
+| **pull**           | Pull both tickets and specs from remote via MCP                                                                        |
+| **pull-tickets**   | Pull only tickets from remote via MCP                                                                                  |
+| **pull-specs**     | Pull only specs from remote via MCP                                                                                    |
+| **document**       | Generate implementation documentation from recent git changes                                                          |
+| **optimize-ai**    | Optimize AI agents and prompts for your project needs                                                                  |
+| **review-changes** | Review recent code changes                                                                                             |
 
-### 1. Create the plugin directory
+### The `implement` workflow
 
-```
-source/plugins/my-plugin/
-├── index.ts         # Plugin definition (exports the HaiPlugin object)
-└── provider.ts      # Provider implementation(s)
-```
+The `implement` prompt orchestrates a multi-phase, domain-parallel coding workflow:
 
-### 2. Implement the `HaiPlugin` interface
-
-```typescript
-import type {ComponentType} from 'react';
-import type {HaiPlugin, CapabilityType, PluginData} from '../types.js';
-
-export const myPlugin: HaiPlugin = {
-	id: 'my-plugin',
-	name: 'My Plugin',
-
-	getCapabilities(): CapabilityType[] {
-		// Declare what this plugin provides: 'tickets', 'specs', 'ai', or any combination
-		return ['tickets'];
-	},
-
-	// React component rendered during `hai init` to collect user config
-	InitStep: ({capability, existingData, onComplete}) => {
-		// Collect credentials or settings, then call:
-		// onComplete({ host: '...', token: '...' })
-	},
-
-	createProvider(capability, data) {
-		// Return a TicketProvider, SpecProvider, or AiProvider
-		// based on the requested capability
-		return new MyTicketProvider(data);
-	},
-
-	// Optional: return project keys for ticket syncing
-	getTicketProjects(data) {
-		return data.projects as string[];
-	},
-
-	// Optional: return a human-readable summary for the wizard
-	summarize(capability, data) {
-		return `My Plugin (${(data as {host: string}).host})`;
-	},
-};
-```
+1. **Fetch** — pulls the target ticket(s) via MCP with recursive linking
+2. **Research** — spawns a `researcher` subagent to read tickets, specs, and codebase patterns
+3. **Plan** — enters plan mode, creates structured TODOs grouped by domain (backend, frontend, etc.)
+4. **Implement** — spawns `backend-dev` and `frontend-dev` subagents **in parallel** for each domain
+5. **Verify** — validates each subagent's output and collects implementation decisions
+
+## Agents
 
-A plugin can provide one or more capabilities:
+HAI installs 7 specialized subagents that prompts can orchestrate:
 
-| Capability | Provider interface | Purpose                       |
-| ---------- | ------------------ | ----------------------------- |
-| `tickets`  | `TicketProvider`   | Fetch and sync tickets        |
-| `specs`    | `SpecProvider`     | Fetch and sync spec pages     |
-| `ai`       | `AiProvider`       | Install AI tool configuration |
+| Agent                 | Role                                                  | Writes code? |
+| --------------------- | ----------------------------------------------------- | ------------ |
+| **researcher**        | Read-only exploration of specs, tickets, and codebase | No           |
+| **architect**         | Designs detailed implementation plans from research   | No           |
+| **backend-dev**       | Implements backend tasks                              | Yes          |
+| **frontend-dev**      | Implements frontend tasks                             | Yes          |
+| **refactorer**        | Refactors existing code                               | Yes          |
+| **security-reviewer** | Reviews code for security issues                      | No           |
+| **verifier**          | Verification and QA                                   | No           |
 
-See [source/types.ts](source/types.ts) for the full provider interfaces.
+Dev agents (`backend-dev`, `frontend-dev`) automatically spawn a `researcher` subagent first to gather context before writing code.
 
-### 3. Register the plugin
+## MCP server
 
-Add your plugin to [source/plugins/index.ts](source/plugins/index.ts):
+The MCP server (`hai mcp`) exposes project context to AI assistants over stdio. It provides two tools:
 
-```typescript
-import {myPlugin} from './my-plugin/index.js';
+| Tool            | Description                                                    |
+| --------------- | -------------------------------------------------------------- |
+| **pull**        | Sync tickets and/or specs from remote to `.ai/`                |
+| **ticket_pull** | Pull a specific ticket by key, with optional recursive linking |
 
-registerPlugin(myPlugin);
+The server also provides instructions that direct AI assistants to read `.ai/specification-index.md` and `.ai/ticket-index.md` for discovering available project context.
+
+## The `.ai/` directory
+
+After running `hai pull`, your project contains:
+
+```
+.ai/
+├── ticket-index.md              # Index of all synced tickets
+├── specification-index.md       # Index of all synced specs
+├── AGENTS.md                    # Auto-generated agent info
+├── tickets/                     # Provider dependent structure (example is for Atlassian)
+│   └── <PROJECT>/
+│       ├── PROJ-101.md
+│       ├── PROJ-102.md
+│       └── ...
+└── specs/                     # Provider dependent structure (example is for Atlassian)
+    └── <SPACE>/
+        ├── page-title.md
+        └── subfolder/
+            └── nested-page.md
 ```
 
-That's it. The plugin will now appear in the `hai init` wizard and be available for configuration.
+Ticket files include: summary, status, assignee, priority, description, comments, and links. Spec files contain the page content converted to Markdown with hierarchy preserved.
 
-### Configuration
+## Configuration
 
-Plugin configuration is stored in `hai.json` at the project root (gitignored). Each entry specifies the plugin ID, the capabilities it provides, and any plugin-specific fields collected during init:
+Running `hai init` creates a `hai.json` at the project root (should be gitignored) that stores provider configuration:
 
 ```json
 {
-	"plugins": [
-		{
-			"plugin": "my-plugin",
-			"provides": ["tickets"],
-			"host": "https://my-service.example.com",
-			"token": "..."
-		}
-	]
+  "plugins": [
+    {
+      "plugin": "atlassian",
+      "provides": ["tickets", "specs"],
+      "host": "https://your-org.atlassian.net",
+      "email": "you@example.com",
+      "token": "...",
+      "projects": ["PROJ"],
+      "spaces": ["TEAM"]
+    },
+    {
+      "plugin": "claude-code",
+      "provides": ["ai"]
+    }
+  ]
 }
 ```
 
-## Data flow
+Use `hai init` again to reconfigure at any time.
 
-1. **Init** — the wizard collects plugin configs and writes `hai.json`
-2. **Pull** — reads config, resolves providers, syncs tickets/specs to `.ai/`
-3. **MCP** — reads config, starts a stdio server, exposes ticket and spec tools to AI assistants
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@2amtech/hai",
-	"version": "0.0.1",
+	"version": "0.0.2",
 	"license": "Apache-2.0",
 	"description": "Helper AI (HAI) is an AI environment initializer setting up a standardized AI workflow supporting multiple AI providers.",
 	"author": "Aleksandar Panic",