@hanhnd/agent-kit 1.0.26 → 1.0.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +25 -208
  2. package/dist/kit-server.js +230 -226
  3. package/dist/tools/handoffs.js +11 -6
  4. package/package.json +8 -8
package/README.md CHANGED
@@ -1,238 +1,55 @@
1
- # Agent-Kit
1
+ # Agent Kit MCP Server
2
2
 
3
- **Super Engineer** — a team of specialized AI agents for software development. Brainstorm ideas, plan implementations, write code, and review PRs using a structured multi-agent workflow.
3
+ This package contains the Agent Kit MCP server used by the Agent Kit plugin manifests.
4
4
 
5
- ## What It Does
6
-
7
- ### Commands
8
-
9
- Agent Kit ships these workflows as skills. In Claude Code, invoke them as slash commands such as `/plan ...`. In Codex or Gemini, ask the agent to use Agent Kit or the named skill, for example: `Use Agent Kit plan for this change`.
10
-
11
- | Skill / Command | Description |
12
- | -------------------------------- | ------------------------------------------------------------------ |
13
- | `/brainstorm [idea]` | Turn a raw idea into an engineer-ready design brief |
14
- | `/scenario [artifact]` | Stress-test requirements, plans, tickets, or reviews for risks |
15
- | `/clarify <file or task>` | Resolve requirement gaps using codebase evidence |
16
- | `/plan [file or idea]` | Create a detailed implementation blueprint |
17
- | `/investigate [issue]` | Trace bugs, errors, or unexpected behavior to root cause |
18
- | `/code [plan or report]` | Implement from a WBS plan or investigation report |
19
- | `/test [intent]` | Add or update focused tests after implementation intent exists |
20
- | `/code-review [diff or target]` | Review diffs, PRs, or commits with evidence-backed findings |
21
- | `/e2e-review [diff or target]` | Review diffs, PRs, or commits with evidence-backed findings |
22
- | `/review [base]` | Review local staged and unstaged changes |
23
- | `/review-pr [PR URL]` | Fetch PR/Jira context, check out the branch, and run code review |
24
- | `/code-simplify [target]` | Improve readability without changing behavior or public shape |
25
- | `/code-refactor [target]` | Analyze structural refactors and produce a refactor proposal |
26
- | `/validate [artifact]` | Validate artifacts directly or by appending `with /validate` |
27
- | `/research [topic]` | Produce source-backed technical research |
28
- | `/debate [subject]` | Run adversarial validation of an analysis, review, or plan |
29
- | `/ticket [ID]` | Fetch a Jira ticket and route it into the planning pipeline |
30
- | `/init` | Extract project DNA for downstream coding and planning workflows |
31
- | `/delegate <agent> <task>` | Delegate to Gemini, Claude, or Codex CLI with optional handoff |
32
- | `/wiki [compile\|query\|lint]` | Maintain and query the persistent project knowledge wiki |
33
-
34
- ---
35
-
36
- ## Wiki
37
-
38
- The wiki is a persistent, compounding knowledge base that accumulates architectural decisions, feature history, patterns, and edge cases across sessions. Unlike conversation memory (which resets), the wiki survives compaction, restarts, and new sessions — it is the long-term institutional memory of your project.
39
-
40
- ### How It's Auto-Populated (Hooks)
41
-
42
- You don't need to run the wiki manually. Five hooks keep it fed automatically:
43
-
44
- - **PostToolUse** — every `kit_save_handoff` call is automatically logged to `.agent-kit/wiki/raw/inbox.md`
45
- - **PreCompact** — before `/compact` discards context, the full session transcript is exported to `.agent-kit/wiki/raw/`
46
- - **PostCompact** — after compaction, the wiki index is re-injected as context so the very next turn has full project knowledge
47
- - **SessionEnd** — before session is cleared, the conversation transcript is exported to `.agent-kit/wiki/raw/`
48
- - **SessionStart (clear)** — after `/clear` resets the session, the wiki index is re-injected so the fresh session starts with full project knowledge
49
-
50
- ### Operations
51
-
52
- | Command | Description |
53
- | -------------------------------- | --------------------------------------------------------------------- |
54
- | `/wiki` or `/wiki compile` | Ingest raw inbox + conversation exports → build/update wiki pages |
55
- | `/wiki query {question}` | Search the wiki and synthesize a cited answer |
56
- | `/wiki lint` | Health-check: broken links, orphan pages, contradictions, stale inbox |
57
-
58
- ### Directory Structure
59
-
60
- ```
61
- .agent-kit/wiki/
62
- ├── raw/
63
- │ ├── inbox.md # Auto-appended by PostToolUse hook (handoff logs)
64
- │ └── conv_*.md # Exported by PreCompact hook (conversation transcripts)
65
- ├── compiled/
66
- │ └── *.md # Structured wiki pages built by /wiki compile
67
- └── archive/
68
- └── *.md # Old raw files moved here after compilation
69
- ```
70
-
71
- ---
72
-
73
- ## Installation
74
-
75
- ### Option 1: Install via GitHub (Recommended)
76
-
77
- Claude Code:
5
+ ## Install
78
6
 
79
7
  ```bash
80
- claude plugin marketplace add https://github.com/hanh-nd/agent-kit
81
- claude plugin install agent-kit
8
+ npm install -g @hanhnd/agent-kit
82
9
  ```
83
10
 
84
- Codex:
11
+ Or run it without a global install:
85
12
 
86
13
  ```bash
87
- codex plugin marketplace add https://github.com/hanh-nd/agent-kit.git
88
- codex
89
- /plugins # then choose agent-kit
14
+ npx -y @hanhnd/agent-kit@latest
90
15
  ```
91
16
 
92
- For Codex hooks, add this to `~/.codex/config.toml`:
93
-
94
- ```toml
95
- [features]
96
- hooks = true
97
- ```
17
+ ## MCP Configuration
98
18
 
99
- **Add credentials** to `~/.claude/credentials` (like `~/.aws/credentials`):
19
+ Claude Code and Codex plugin manifests already use this package:
100
20
 
101
- ```bash
102
- touch ~/.claude/credentials && chmod 600 ~/.claude/credentials
21
+ ```json
22
+ {
23
+ "kit-agents": {
24
+ "command": "npx",
25
+ "args": ["-y", "@hanhnd/agent-kit@latest"]
26
+ }
27
+ }
103
28
  ```
104
29
 
105
- ```ini
106
- [default]
107
- ATLASSIAN_CLOUD_ID = your-atlassian-cloud-id
108
- ATLASSIAN_USER_EMAIL = you@yourcompany.com
109
- ATLASSIAN_API_TOKEN = your-atlassian-api-token
110
- BITBUCKET_USER_EMAIL = you@yourcompany.com
111
- BITBUCKET_API_TOKEN = your-atlassian-api-token
112
- BITBUCKET_DEFAULT_WORKSPACE = your-default-workspace-slug
113
- ```
114
-
115
- To use multiple profiles, add `[work]`, `[personal]`, etc. sections and set `KIT_PROFILE=work` in your environment.
116
-
117
- To update: `claude plugin update agent-kit`
118
- To uninstall: `claude plugin uninstall agent-kit`
119
-
120
- ---
121
-
122
- ### Option 2: Clone and Install Locally
123
-
124
- Use this if you want to modify the plugin or develop against it.
30
+ ## Development
125
31
 
126
- **1. Clone and build**
32
+ From the repository root:
127
33
 
128
34
  ```bash
129
- git clone https://github.com/hanh-nd/agent-kit.git
130
- cd agent-kit
131
35
  npm install
132
- npm run build
133
- ```
134
-
135
- **2. Register the plugin**
136
-
137
- Claude Code:
138
-
139
- ```bash
140
- claude plugin marketplace add /absolute/path/to/agent-kit
141
- claude plugin install agent-kit
36
+ npm run build --workspace @hanhnd/agent-kit
142
37
  ```
143
38
 
144
- Codex:
39
+ From this directory:
145
40
 
146
41
  ```bash
147
- codex plugin marketplace add /absolute/path/to/agent-kit
148
- codex
149
- /plugins # then choose agent-kit
150
- ```
151
-
152
- For Codex hooks, add this to `~/.codex/config.toml`:
153
-
154
- ```toml
155
- [features]
156
- hooks = true
157
- ```
158
-
159
- **3. Add credentials** to `~/.claude/credentials` for MCP integrations:
160
-
161
- ```bash
162
- touch ~/.claude/credentials && chmod 600 ~/.claude/credentials
163
- ```
164
-
165
- ```ini
166
- [default]
167
- ATLASSIAN_CLOUD_ID = your-atlassian-cloud-id
168
- ATLASSIAN_USER_EMAIL = you@yourcompany.com
169
- ATLASSIAN_API_TOKEN = your-atlassian-api-token
170
- BITBUCKET_USER_EMAIL = you@yourcompany.com
171
- BITBUCKET_API_TOKEN = your-atlassian-api-token
172
- BITBUCKET_DEFAULT_WORKSPACE = your-default-workspace-slug
173
- ```
174
-
175
- **4. Verify**
176
-
177
- ```
178
- /brainstorm test idea
42
+ npm run build
179
43
  ```
180
44
 
181
- ---
182
-
183
- ### Option 3: Install as Gemini Extension (Optional)
184
-
185
- If you want to reuse the commands with [Gemini CLI](https://geminicli.com) (for `/delegate` to Gemini), install it using:
186
-
187
- ```bash
188
- git clone https://github.com/hanh-nd/agent-kit.git
189
- cd agent-kit/plugins/agent-kit
190
- gemini extension link .gemini
191
- ```
45
+ The source lives in `src/` and the published binary is `dist/kit-server.js`.
192
46
 
193
- ---
47
+ ## Publishing
194
48
 
195
- ## Development
49
+ Publish the MCP package from the repository root:
196
50
 
197
51
  ```bash
198
- # Build once
199
- npm run build
200
-
201
- # Watch mode (rebuilds on file changes)
202
- npm run dev
52
+ npm run publish:mcp
203
53
  ```
204
54
 
205
- The MCP server source is in `src/`. Agent personas are in `agents/`. Canonical skill modules are in `skills/`; `npm run build:skills` generates provider-safe copies into `.claude/skills/`, `.codex/skills/`, and `.gemini/skills/`.
206
-
207
- ---
208
-
209
- ## Requirements
210
-
211
- - Node.js 18+
212
- - Claude Code, Codex, or Gemini CLI
213
-
214
- ---
215
-
216
- ## Integrations
217
-
218
- Credentials are stored in `~/.claude/credentials` (INI format). Keys can also be set as environment variables — env vars take priority (useful for CI/CD).
219
-
220
- ### Jira (via Atlassian REST API)
221
-
222
- Used by `/ticket` and `/review-pr`.
223
-
224
- | Key | Description |
225
- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
226
- | `ATLASSIAN_CLOUD_ID` | Your Atlassian Cloud ID — find it at [admin.atlassian.com](https://admin.atlassian.com) under your site settings |
227
- | `ATLASSIAN_USER_EMAIL` | Your Atlassian account email |
228
- | `ATLASSIAN_API_TOKEN` | API token — create at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens) |
229
-
230
- ### Bitbucket Cloud (via Bitbucket REST API)
231
-
232
- Used by `/review-pr`.
233
-
234
- | Key | Description |
235
- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
236
- | `BITBUCKET_USER_EMAIL` | Your Atlassian account email (same as Jira) |
237
- | `BITBUCKET_API_TOKEN` | API token — create at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens) |
238
- | `BITBUCKET_DEFAULT_WORKSPACE` | Default workspace slug — used when passing a numeric PR ID without a `workspace` param |
55
+ That script runs `npm publish --workspace @hanhnd/agent-kit`, so npm publishes this `mcp/` package instead of the plugin bundle under `plugins/agent-kit`.