@luanpdd/kit-mcp 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -6,6 +6,54 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-05-03
+
+### Fixed
+- `src/mcp-server/index.js` was importing `DEFAULT_KIT_ROOT` from `core/kit.js`, but that export was renamed to `BUNDLED_KIT_ROOT` / `resolveKitRoot` during the v0.2.0 refactor. The unused import wasn't caught by CI (which only smoke-tests CLI commands, not MCP server boot) and made the server crash on `npx -y @luanpdd/kit-mcp` for any sync/install command. Removed the dead import — server now boots cleanly.
+
+### Tests (suggestion)
+- CI should boot `node bin/mcp.js` and validate exit. Tracked in roadmap.
+
+## [0.4.0] - 2026-05-03
+
+### Changed
+- README rewritten: bundled workflow framed as the default install path; `--kit-root` framed as the escape hatch for users who want to replace it entirely.
+- "What ships in the box" lists actual bundled folders (19 agents, 60 commands, framework, hooks) instead of "example kit".
+- Quick start reordered: use bundled as-is first, replace with own kit second.
+- CLI examples updated with real counts.
+
+This release is content-equivalent to 0.3.0 plus the documentation overhaul. No code changes versus 0.3.0.
+
+## [0.3.0] - 2026-05-03
+
+**Reverts the v0.2.0 cleanup.** kit-mcp goes back to shipping an opinionated, embedded workflow — installing `@luanpdd/kit-mcp` once again gives you the maintainer's brownfield planning workflow (PT-BR) ready to use. The "generic infrastructure, bring your own kit" framing of v0.2.0 was based on the wrong premise: the bundled content **is** the maintainer's workflow, intentionally distributed for anyone to inherit. The `--kit-root` / `KIT_MCP_KIT_ROOT` escape hatch from v0.2.0 stays — point it at your own folder if you want to replace the bundled workflow entirely.
+
+### Restored
+- 19 agents — planner, executor, verifier, debugger, codebase-mapper, ui-auditor, ui-checker, ui-researcher, advisor-researcher, assumptions-analyzer, integration-checker, nyquist-auditor, phase-researcher, plan-checker, project-researcher, research-synthesizer, roadmapper, user-profiler (plus the example-reviewer kept from 0.2.0).
+- 60 slash-commands in PT-BR — milestone lifecycle (`/novo-marco`, `/concluir-marco`, `/auditar-marco`, `/planejar-lacunas`, `/resumo-marco`), phase lifecycle (`/discutir-fase`, `/planejar-fase`, `/executar-fase`, `/validar-fase`, `/verificar-trabalho`, `/adicionar-fase`, `/inserir-fase`, `/remover-fase`), task & idea capture (`/adicionar-tarefa`, `/nota`, `/plantar-ideia`, `/adicionar-backlog`, `/revisar-backlog`), workflows (`/autonomo`, `/expresso`, `/rapido`, `/fazer`, `/proximo`, `/fluxos-trabalho`), debugging (`/depurar`, `/forense`), publishing (`/publicar`, `/setup-notion`, `/branch-pr`), and more.
+- `kit/framework/` — workflows + templates + bin libs the agents and commands delegate into.
+- `kit/hooks/` — workflow guards, prompt guards, statusline.
+- `kit/COMANDOS.md`, `kit/file-manifest.json`, `kit/settings.json`.
+
+### Not restored (intentionally)
+- The 13 skills from the Anthropic Cowork ecosystem (paperclip, design-guide, company-creator, paperclip-create-agent, paperclip-create-plugin, release, release-changelog, prcheckloop, pr-report, doc-maintenance, deal-with-security-advisory, create-agent-adapter, para-memory-files). These belong to Anthropic, not to this package — install them separately if you want them.
+
+### Changed
+- `kit/commands/setup-notion.md` — hardcoded Notion page ID and "Trynux" workspace name replaced with placeholder `{NOTION_PARENT_PAGE_ID}` configurable via env var `KIT_NOTION_PARENT_PAGE_ID`.
+- `kit/commands/publicar.md` — hardcoded GitHub repo URL `IEP-Advocacia/obsidian-chat-trynux` replaced with placeholder `${OBSIDIAN_VAULT_REPO}` configurable via env var `OBSIDIAN_VAULT_REPO`. If the env var isn't set, the Obsidian publishing step is skipped cleanly.
+- README rewritten: bundled workflow framed as the default install path; `--kit-root` framed as the escape hatch for users who want to replace it entirely.
+
+### Migration
+
+If you installed v0.2.0 expecting the empty/example kit and don't want the bundled workflow, set `KIT_MCP_KIT_ROOT` to your own kit folder before any sync command — nothing else changes:
+
+```bash
+export KIT_MCP_KIT_ROOT=~/my-kit
+npx -y @luanpdd/kit-mcp sync install claude-code --project-root .
+```
+
+If you were on v0.1.x and want the original bundled workflow back, just upgrade — `npm install @luanpdd/kit-mcp@latest` ships it again. (Note: the Anthropic Cowork skills bundled in 0.1.x are still excluded.)
+
 ## [0.2.0] - 2026-05-03
 
 **BREAKING.** kit-mcp is now generic infrastructure. The bundled "personal kit" content was removed — bring your own via `--kit-root` or `KIT_MCP_KIT_ROOT`.
@@ -110,7 +158,10 @@ npx -y @luanpdd/kit-mcp sync install claude-code --project-root .
 - CLI mirror of all MCP tools.
 - `install` command that registers kit-mcp into an IDE's MCP config (JSON for Claude/Cursor/Gemini/Windsurf, TOML for Codex).
 
-[Unreleased]: https://github.com/luanpdd/kit-mcp/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/luanpdd/kit-mcp/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/luanpdd/kit-mcp/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/luanpdd/kit-mcp/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/luanpdd/kit-mcp/compare/v0.2.1...v0.3.0
 [0.2.0]: https://github.com/luanpdd/kit-mcp/compare/v0.1.6...v0.2.0
 [0.1.6]: https://github.com/luanpdd/kit-mcp/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/luanpdd/kit-mcp/compare/v0.1.4...v0.1.5

package/README.md

@@ -5,11 +5,11 @@
 [![CI](https://github.com/luanpdd/kit-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/luanpdd/kit-mcp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Generic infrastructure to ship **your personal kit** of agents, slash-commands and skills as an **MCP server**, with one-shot **sync** that projects the kit into every supported IDE's native layout — Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Antigravity, Copilot, Trae.
+An opinionated **brownfield planning workflow** (in PT-BR) — agents, slash-commands, framework — shipped as an **MCP server**, with one-shot **sync** that projects the kit into every supported IDE's native layout — Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Antigravity, Copilot, Trae.
 
 > **One canonical source. N IDEs. Edit once, everywhere updated.**
 >
-> Bring your own `kit/` folder, or extend the bundled example.
+> Install and inherit the bundled workflow, or point `--kit-root` at your own folder to replace it entirely.
 
 ---
 
@@ -27,11 +27,15 @@ Inspired by [vinilana/dotcontext](https://github.com/vinilana/dotcontext) — se
 
 ```
 kit-mcp/
-├── kit/                        ← bundled EXAMPLE kit (replace with your own)
-│   ├── agents/example-reviewer.md
-│   ├── commands/example-greeting.md
-│   ├── skills/example-skill/SKILL.md
-│   └── README.md               format guide
+├── kit/                        ← bundled brownfield workflow (PT-BR)
+│   ├── agents/                 19 agents (planner, executor, verifier, debugger,
+│   │                                      ui-auditor, codebase-mapper, …)
+│   ├── commands/               60 slash-commands (/novo-marco, /planejar-fase,
+│   │                                              /executar-fase, /publicar, …)
+│   ├── framework/              workflows + templates + bin libs the agents use
+│   ├── hooks/                  workflow guards, prompt guards, statusline
+│   ├── skills/example-skill/   single example skill (replace with your own)
+│   └── README.md               file-format guide
 │
 ├── gates/                      ← reusable workflow gates (regression, confidence, dep-check, …)
 │
@@ -53,6 +57,12 @@ kit-mcp/
 
 **Lines of source code:** ~1100. **Runtime dependencies:** 3 (`@modelcontextprotocol/sdk`, `commander`, `chokidar`). **Build step:** none — plain ESM Node.js 20+.
 
+### About the bundled workflow
+
+The bundled `kit/` is an opinionated **brownfield planning workflow** in Portuguese — milestones, phases, requirements, planning, execution with atomic commits and checkpoints, retrospective auditing. Installing `@luanpdd/kit-mcp` and syncing into your IDE gives you all 60 slash-commands, 19 agents, plus the framework templates that they delegate into.
+
+If that's not what you want, point `--kit-root` at your own folder and ignore everything under `kit/` — the infrastructure (registry, sync, gates, forensics, MCP server) works the same regardless of what kit you load.
+
 ---
 
 ## Prerequisites
@@ -65,14 +75,21 @@ kit-mcp/
 
 ## Quick start
 
-### 1. Try the example kit (no setup)
+### 1. Use the bundled workflow as-is (recommended)
 
 ```bash
-npx -y @luanpdd/kit-mcp kit list-agents     # see the bundled example agent
-npx -y @luanpdd/kit-mcp sync targets        # see all supported IDEs
+# Browse what's bundled
+npx -y @luanpdd/kit-mcp kit list-agents     # 19 agents
+npx -y @luanpdd/kit-mcp kit list-commands   # 60 commands
+npx -y @luanpdd/kit-mcp sync targets        # supported IDEs
+
+# Install into your project for Claude Code
+npx -y @luanpdd/kit-mcp sync install claude-code --project-root .
 ```
 
-### 2. Bring your own kit
+After that, open the project in Claude Code and the slash-commands (`/novo-marco`, `/planejar-fase`, `/executar-fase`, `/publicar`, …) and agents are immediately available.
+
+### 2. Replace the bundled workflow with your own kit
 
 Point kit-mcp at your own `kit/` folder via `--kit-root` or the `KIT_MCP_KIT_ROOT` env var:
 
@@ -86,7 +103,7 @@ export KIT_MCP_KIT_ROOT=~/my-kit
 npx -y @luanpdd/kit-mcp sync install claude-code --project-root .
 ```
 
-Your `~/my-kit/` follows the same layout as the bundled example:
+Your `~/my-kit/` follows the same layout as the bundled kit:
 
 ```
 my-kit/
@@ -116,11 +133,11 @@ The CLI mirrors the MCP tools 1:1. Output is always JSON to stdout. The global `
 ### `kit kit ...` — browse the kit
 
 ```bash
-kit kit list-agents               # bundled example: 1 agent
-kit kit list-commands             # bundled example: 1 command
-kit kit list-skills               # bundled example: 1 skill
-kit kit get agent example-reviewer
-kit kit search "review"           # fuzzy match across all kinds
+kit kit list-agents               # 19 agents (bundled workflow)
+kit kit list-commands             # 60 commands (bundled workflow)
+kit kit list-skills               # 1 skill (example only — bring your own)
+kit kit get agent planner
+kit kit search "milestone"        # fuzzy match across all kinds
 ```
 
 ### `kit sync ...` — project into an IDE
@@ -453,7 +470,7 @@ PRs welcome.
 ## Smoke tests
 
 ```bash
-node bin/cli.js kit list-agents | head -5         # bundled example agent
+node bin/cli.js kit list-agents | head -5         # 19 bundled agents
 node bin/cli.js sync targets                      # 8 IDEs
 node bin/cli.js gates list                        # 5 gates
 node bin/cli.js install dry-run claude-code --via npx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luanpdd/kit-mcp",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Generic infrastructure to ship YOUR personal kit of agents/commands/skills as an MCP server, with cross-IDE sync (Claude Code, Cursor, Codex, Gemini, Windsurf, Antigravity, Copilot, Trae).",
   "type": "module",
   "bin": {

package/src/mcp-server/index.js

@@ -12,7 +12,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 
-import { listKit, searchKit, findItem, DEFAULT_KIT_ROOT } from '../core/kit.js';
+import { listKit, searchKit, findItem } from '../core/kit.js';
 import { listTargets } from '../core/registry.js';
 import { syncTo, statusOf, removeFrom } from '../core/sync.js';
 import { detectReverse, applyReverse } from '../core/reverse-sync.js';