@aladac/hu 0.1.0-a1

package/doc/claude-code/plugins.md

@@ -0,0 +1,273 @@
+---
+source: https://code.claude.com/docs/en/plugins
+fetched: 2026-01-13
+---
+
+# Claude Code Plugins
+
+Plugins extend Claude Code with custom slash commands, agents, hooks, Skills, and MCP servers. They can be shared across projects and teams through marketplaces.
+
+## When to Use Plugins vs Standalone
+
+| Approach | Command Names | Best For |
+|----------|---------------|----------|
+| **Standalone** (`.claude/` directory) | `/hello` | Personal workflows, project-specific, quick experiments |
+| **Plugins** (`.claude-plugin/plugin.json`) | `/plugin-name:hello` | Team sharing, community distribution, reusable across projects |
+
+**Use standalone** when customizing for a single project, personal use, experimenting, or wanting short command names.
+
+**Use plugins** when sharing with teams/community, needing the same commands across projects, wanting version control, or distributing through marketplaces.
+
+Start with standalone in `.claude/` for quick iteration, then convert to a plugin when ready to share.
+
+## Installation
+
+### Using the /plugin Command
+
+```bash
+# Add a marketplace first
+/plugin marketplace add user-or-org/repo-name
+
+# Then browse and install plugins
+/plugin
+```
+
+### Community CLI Tool
+
+```bash
+npx claude-plugins install @anthropics/claude-code-plugins/frontend-design
+```
+
+Requires Claude Code v1.0.33 or higher.
+
+## Creating Plugins
+
+### Quickstart
+
+1. **Create the plugin directory:**
+```bash
+mkdir my-plugin
+mkdir my-plugin/.claude-plugin
+```
+
+2. **Create the manifest** (`my-plugin/.claude-plugin/plugin.json`):
+```json
+{
+  "name": "my-plugin",
+  "description": "A greeting plugin to learn the basics",
+  "version": "1.0.0",
+  "author": {
+    "name": "Your Name"
+  }
+}
+```
+
+3. **Add a slash command** (`my-plugin/commands/hello.md`):
+```markdown
+---
+description: Greet the user with a friendly message
+---
+
+# Hello Command
+
+Greet the user named "$ARGUMENTS" warmly and ask how you can help them today.
+```
+
+4. **Test your plugin:**
+```bash
+claude --plugin-dir ./my-plugin
+```
+
+Then run `/my-plugin:hello Alex`.
+
+## Plugin Structure
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json          # Required: plugin metadata
+├── commands/                # Slash commands
+│   └── hello.md
+├── agents/                  # Custom agent definitions
+├── skills/                  # Agent Skills
+│   └── skill-name/
+│       └── SKILL.md
+├── hooks/                   # Event handlers
+│   └── hooks.json
+├── .mcp.json               # MCP server configurations
+├── .lsp.json               # LSP server configurations
+└── README.md               # Documentation
+```
+
+**Important:** Don't put `commands/`, `agents/`, `skills/`, or `hooks/` inside `.claude-plugin/`. Only `plugin.json` goes there.
+
+## Plugin Components
+
+### Slash Commands
+
+Create Markdown files in `commands/`. The filename becomes the command name, prefixed with the plugin namespace:
+
+```markdown
+---
+description: Description shown in command menu
+---
+
+# Command Title
+
+Your prompt instructions here. Use $ARGUMENTS for user input.
+Use $1, $2 for individual parameters.
+```
+
+### Agent Skills <!-- updated: 2026-01-13 -->
+
+Skills are model-invoked capabilities that Claude automatically uses based on task context. Create `skills/skill-name/SKILL.md`:
+
+```markdown
+---
+name: code-review
+description: Reviews code for best practices. Use when reviewing code or PRs.
+---
+
+When reviewing code, check for:
+1. Code organization and structure
+2. Error handling
+3. Security concerns
+4. Test coverage
+```
+
+After installing the plugin, restart Claude Code to load the Skills.
+
+### Hooks
+
+Create `hooks/hooks.json`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{ "type": "command", "command": "npm run lint:fix $FILE" }]
+      }
+    ]
+  }
+}
+```
+
+### LSP Servers <!-- updated: 2026-01-13 -->
+
+For common languages (TypeScript, Python, Rust), install pre-built LSP plugins from official marketplaces. Create custom LSP plugins only for languages not already covered.
+
+Create `.lsp.json` for language server support:
+
+```json
+{
+  "go": {
+    "command": "gopls",
+    "args": ["serve"],
+    "extensionToLanguage": {
+      ".go": "go"
+    }
+  }
+}
+```
+
+Users must have the language server binary installed on their machine.
+
+### MCP Servers
+
+Create `.mcp.json` for external tool integration:
+
+```json
+{
+  "servers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["my-mcp-server"]
+    }
+  }
+}
+```
+
+## Official Plugins
+
+| Name | Description |
+|------|-------------|
+| **agent-sdk-dev** | Development kit for Claude Agent SDK projects |
+| **code-review** | Automated PR review using multiple specialized agents |
+| **commit-commands** | Git workflow: `/commit`, `/commit-push-pr`, `/clean_gone` |
+| **feature-dev** | 7-phase feature development with explorer, architect, reviewer agents |
+| **frontend-design** | Create distinctive, production-grade frontend interfaces |
+| **hookify** | Create custom hooks to prevent unwanted behaviors |
+| **plugin-dev** | Toolkit for developing Claude Code plugins |
+| **pr-review-toolkit** | Comprehensive PR review with 6 specialized reviewers |
+| **security-guidance** | Security reminder hook (injection, XSS, eval, etc.) |
+
+## Testing and Debugging
+
+### Load During Development
+
+```bash
+# Single plugin
+claude --plugin-dir ./my-plugin
+
+# Multiple plugins
+claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two
+```
+
+### Verify Components
+
+- Run commands with `/command-name`
+- Check agents appear in `/agents`
+- Verify hooks trigger correctly
+- Use validation and debugging tools (see Plugins reference)
+
+## Migrating Standalone to Plugin
+
+1. Create plugin structure:
+```bash
+mkdir -p my-plugin/.claude-plugin
+```
+
+2. Create manifest (`my-plugin/.claude-plugin/plugin.json`)
+
+3. Copy existing files:
+```bash
+cp -r .claude/commands my-plugin/
+cp -r .claude/agents my-plugin/
+cp -r .claude/skills my-plugin/
+```
+
+4. Migrate hooks from `.claude/settings.json` to `my-plugin/hooks/hooks.json`
+
+5. Test with `claude --plugin-dir ./my-plugin`
+
+## Publishing
+
+### Plugin Manifest Optional Fields
+
+```json
+{
+  "name": "my-plugin",
+  "description": "Plugin description",
+  "version": "1.0.0",
+  "author": { "name": "Your Name" },
+  "homepage": "https://example.com",
+  "repository": "https://github.com/user/repo",
+  "license": "MIT",
+  "keywords": ["utility", "workflow"]
+}
+```
+
+### Creating a Marketplace
+
+To host a marketplace, create a git repository with `.claude-plugin/marketplace.json`. See the [plugin marketplaces documentation](https://code.claude.com/docs/en/plugin-marketplaces) for details.
+
+## Resources
+
+- [Official Plugin Docs](https://code.claude.com/docs/en/plugins)
+- [Plugins Reference](https://code.claude.com/docs/en/plugins-reference)
+- [Discover Plugins](https://code.claude.com/docs/en/discover-plugins)
+- [Plugin Marketplaces](https://code.claude.com/docs/en/plugin-marketplaces)
+- [Agent Skills](https://code.claude.com/docs/en/skills)
+- [Anthropic Official Plugins](https://github.com/anthropics/claude-code/tree/main/plugins)

package/doc/claude-code/sdk-protocols.md

@@ -0,0 +1,202 @@
+---
+source: https://github.com/anthropics/claude-agent-sdk-typescript
+additional_sources:
+  - https://github.com/modelcontextprotocol/typescript-sdk
+  - https://github.com/agentclientprotocol/agent-client-protocol
+  - https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk
+fetched: 2026-01-13
+---
+
+# Claude Code SDK & Protocols
+
+The packages powering Claude Code's capabilities.
+
+## @anthropic-ai/claude-agent-sdk
+
+The Claude Agent SDK enables programmatic building of AI agents with Claude Code's capabilities.
+
+**Install**:
+```bash
+npm install @anthropic-ai/claude-agent-sdk
+```
+
+**Package**: 71.7 MB, v0.2.5 (as of 2026-01)
+
+**Key exports**:
+```typescript
+import {
+  query,                    // Main entry point (async iterator)
+  type Options,
+  type Query,
+  type SDKMessage,
+  type SDKResultMessage,
+  type AgentDefinition,
+  type PermissionResult,
+  type HookCallback,
+  // V2 API (unstable)
+  unstable_v2_createSession,
+  unstable_v2_resumeSession,
+  unstable_v2_prompt,
+  // MCP tools
+  createSdkMcpServer,
+  tool,
+} from '@anthropic-ai/claude-agent-sdk';
+```
+
+**Features**:
+- Context management
+- Permission model
+- Session & error management
+- Built-in tools (file ops, Bash, web search)
+- MCP integration for custom tools
+
+**Authentication**:
+- `ANTHROPIC_API_KEY` environment variable
+- Or `apiKey` in config
+- Also supports AWS Bedrock and Google Vertex AI
+
+**Resources**:
+- [GitHub](https://github.com/anthropics/claude-agent-sdk-typescript)
+- [npm](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)
+- [Docs](https://docs.claude.com/en/api/agent-sdk/overview)
+- [Migration Guide](https://docs.claude.com/en/docs/claude-code/sdk/migration-guide) (from Claude Code SDK)
+
+---
+
+## @modelcontextprotocol/sdk (MCP)
+
+The Model Context Protocol standardizes how applications provide context for LLMs.
+
+**Install** (v2 - pre-alpha, v1.x recommended for production):
+```bash
+# Server
+npm install @modelcontextprotocol/server zod
+
+# Client  
+npm install @modelcontextprotocol/client zod
+```
+
+**Package**: v1.25.2 stable, v2 in development (Q1 2026)
+
+**Requires**: Zod ^3.25 peer dependency
+
+**Concepts**:
+- **Tools**: Let LLMs ask your server to take actions
+- **Resources**: Expose read-only data to clients/models
+- **Prompts**: Reusable templates for consistent interaction
+- **Sampling**: Server-side tools can request LLM completions
+
+**Transports**:
+- **Streamable HTTP** (recommended for remote servers)
+- **stdio** (standard I/O)
+- HTTP + SSE (backwards compatibility only)
+
+**Documentation**:
+- [docs/server.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/server.md) - Building servers
+- [docs/client.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/client.md) - Building clients
+- [docs/capabilities.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/capabilities.md) - Sampling, elicitation
+- [MCP Specification](https://spec.modelcontextprotocol.io)
+- [modelcontextprotocol.io](https://modelcontextprotocol.io)
+
+---
+
+## @agentclientprotocol/sdk (ACP)
+
+The Agent Client Protocol standardizes communication between code editors and coding agents.
+
+**Install**:
+```bash
+npm install @agentclientprotocol/sdk
+```
+
+**Communication**: JSON-RPC over stdio
+
+**Relationship to MCP**: ACP reuses MCP specifications where possible, adding editor-specific types. MCP handles "what" (data/tools), ACP handles "where" (editor integration).
+
+**Supported Editors**:
+- Zed
+- Neovim
+- Marimo
+- JetBrains (in progress)
+
+**Supported Agents**:
+- Claude Code
+- Codex CLI
+- Gemini CLI
+- goose
+- StackPack
+
+**Official Libraries**:
+- TypeScript: `@agentclientprotocol/sdk`
+- Python: `python-sdk`
+- Rust: `agent-client-protocol` (crates.io)
+- Kotlin: `acp-kotlin`
+
+**Resources**:
+- [agentclientprotocol.com](https://agentclientprotocol.com/)
+- [GitHub](https://github.com/agentclientprotocol/agent-client-protocol)
+- [Schema](https://github.com/agentclientprotocol/agent-client-protocol/blob/main/schema/schema.json)
+
+---
+
+## Protocol Relationships
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Code Editor                              │
+│                  (Zed, JetBrains, etc.)                     │
+└─────────────────────────┬───────────────────────────────────┘
+                          │ ACP (JSON-RPC/stdio)
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Coding Agent                              │
+│               (Claude Code, Gemini CLI)                      │
+│                          │                                   │
+│    ┌─────────────────────┼─────────────────────┐            │
+│    │                     │                     │            │
+│    ▼                     ▼                     ▼            │
+│ Built-in Tools      MCP Servers         LLM API            │
+│ (File, Bash)     (custom tools)     (Anthropic)           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**ACP**: Editor ↔ Agent communication
+**MCP**: Agent ↔ Tools/Data communication  
+**Agent SDK**: Building agents with Claude capabilities
+
+---
+
+## Using with honbu
+
+These protocols enable honbu hook integration:
+
+### As MCP Server
+
+honbu could expose tools via MCP:
+```typescript
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+
+const server = createSdkMcpServer({
+  tools: [
+    tool({
+      name: 'chi_data_search',
+      description: 'Search Claude Code session data',
+      parameters: z.object({ query: z.string() }),
+      execute: async ({ query }) => {
+        // Search sessions, return results
+      }
+    })
+  ]
+});
+```
+
+### As Hook Handler
+
+honbu receives hook events (JSON via stdin) and returns decisions (JSON via stdout), fitting naturally into the ACP/MCP ecosystem.
+
+### Data Access Layer
+
+The SDK's session/context management aligns with honbu's data access goals:
+- Read session transcripts
+- Query knowledge base
+- Track tool usage patterns

package/document-manifest.toml

@@ -0,0 +1,29 @@
+[[docs]]
+path = "doc/claude-code/hooks.md"
+source = "https://code.claude.com/docs/en/hooks"
+fetched = "2026-01-13"
+
+[[docs]]
+path = "doc/claude-code/capabilities.md"
+source = "https://code.claude.com/docs/en/cli-reference"
+fetched = "2026-01-13"
+
+[[docs]]
+path = "doc/claude-code/overview.md"
+source = "https://code.claude.com/docs/en/overview"
+fetched = "2026-01-13"
+
+[[docs]]
+path = "doc/claude-code/plugins.md"
+source = "https://code.claude.com/docs/en/plugins"
+fetched = "2026-01-13"
+
+[[docs]]
+path = "doc/claude-code/directory-structure.md"
+source = "https://idsc2025.substack.com/p/the-complete-technical-guide-to-claude"
+fetched = "2026-01-13"
+
+[[docs]]
+path = "doc/claude-code/sdk-protocols.md"
+source = "https://github.com/anthropics/claude-agent-sdk-typescript"
+fetched = "2026-01-13"

package/justfile

@@ -0,0 +1,39 @@
+# hu (@aladac/hu)
+
+default: lint-fix format typecheck
+
+# Development
+dev:
+    npm run dev
+
+test:
+    npm test
+
+lint:
+    npm run lint
+
+lint-fix:
+    npm run lint:fix
+
+format:
+    npm run format
+
+typecheck:
+    npm run typecheck
+
+# Install/reinstall globally
+install:
+    npm install && npm link
+
+# Version bumping
+# Usage: just bump [patch|minor|major]
+# - No args: bump pre-release number (1.0.0-pre1 -> 1.0.0-pre2)
+# - patch: bump patch version (1.0.0 -> 1.0.1)
+# - minor: bump minor version (1.0.0 -> 1.1.0)
+# - major: bump major version (1.0.0 -> 2.0.0)
+bump *args:
+    npx tsx src/commands/bump.ts {{args}}
+
+# Clean
+clean:
+    rm -rf node_modules

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@aladac/hu",
+  "version": "0.1.0-a1",
+  "description": "CLI tools for Claude Code workflows",
+  "type": "module",
+  "bin": {
+    "hu": "./src/index.ts"
+  },
+  "scripts": {
+    "dev": "node src/index.ts",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "cheerio": "^1.1.2",
+    "citty": "^0.1.6",
+    "turndown": "^7.2.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@types/node": "^22.0.0",
+    "@types/turndown": "^5.0.5",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=23.6.0"
+  }
+}