improve

ai-dp:improve

Self-modifying meta-skill. Lets the plugin author iterate on this plugin from inside a Claude Code session: identify the right file, preview the edit, apply, bump version, commit.

Inputs

• $ARGUMENTS — free-text feedback (e.g. "make ai-dp:decisions also record rejected libraries", "add a section to ai-dp:investigation for external dependencies").
• ${AIDP_PLUGIN_ROOT} — always set when this skill runs; points to the plugin source.

Procedure

1. Resolve and validate the plugin source path

• Read ${AIDP_PLUGIN_ROOT}.

• If the path contains /.claude/plugins/cache/ → REFUSE with this exact message and stop:

  ai-dp:improve cannot run against a marketplace-installed plugin: ${AIDP_PLUGIN_ROOT} is in the plugin cache, and any edits would be overwritten the next time the marketplace catalog is refreshed.

  To work on the plugin:

  1. Fork or clone [email protected]:kostia-official/claude-ai-dev-pipeline-plugin.git to a local directory (e.g. ~/projects/claude-ai-dev-pipeline-plugin/).
  2. Run with claude --plugin-dir <local-clone>, or /plugin install <local-clone>.
  3. Re-run /ai-dp:improve <your feedback>.

• Otherwise confirm with git -C ${AIDP_PLUGIN_ROOT} rev-parse --show-toplevel that the directory is a git repo. If not, refuse and tell the user the plugin source must be a git repo.

• Check git -C ${AIDP_PLUGIN_ROOT} status --porcelain for uncommitted changes inside the plugin tree. If any exist, REFUSE: tell the user to commit or stash those changes first so the auto-commit doesn't pull in unrelated work. Allow override only via explicit AskUserQuestion confirmation.

2. Understand the request

Parse $ARGUMENTS. If genuinely ambiguous (you can't tell what file or behavior to change), ask one clarifying AskUserQuestion — never more.

3. Identify target file(s)

Map intent to one of:

• skills/<step>/SKILL.md — for skill behavior changes.
• commands/dev-pipeline.md — for orchestrator changes (argument classification, hand-off rules).
• scripts/lib/*.ts — for state/findRun helper changes.
• scripts/cli/*.ts — for state CLI helper changes.
• scripts/hooks/*.ts — for hook behavior changes.
• .claude-plugin/plugin.json — for Claude Code manifest changes (NB: version is bumped in step 6, not via this path).
• .claude-plugin/marketplace.json — for marketplace metadata.
• hooks/hooks.json — for hook config.
• README.md — for documentation changes.

When multiple files plausibly match, list them with the suggested edit summary and ask AskUserQuestion: which to apply? Include "All of them" if appropriate.

4. Preview the diff

Read current file content. Draft the edit. Show the user a unified-diff-style preview in chat:

--- a/<path>
+++ b/<path>
@@ ... @@
-<removed line>
+<added line>

Then ask AskUserQuestion:

• Apply — proceed.
• Modify (give more direction) — capture user feedback, redraft, loop back.
• Cancel — stop, no changes made.

5. Apply the edit

Use Edit (or Write for new files).

6. Bump version — all 3 fields in lockstep

Read the current version from .claude-plugin/plugin.json. Verify the same version across all 3 fields: .claude-plugin/plugin.json (version) and .claude-plugin/marketplace.json (top-level version AND plugins[0].version). If ANY are out of sync, REFUSE and tell the user to manually align them first.

Default bump is PATCH (X.Y.Z → X.Y.(Z+1)).

If the change matches "substantive" heuristics, ask AskUserQuestion with options PATCH / MINOR / MAJOR:

• MINOR: added a new skill, added a new orchestrator capability, added a new state.json field that's optional, added a new platform target.
• MAJOR: removed/renamed an existing skill, changed state.json schema in a non-additive way, changed a hook contract, changed the orchestrator's argument classifier in an incompatible way.

Write the new version back into ALL of:

• .claude-plugin/plugin.json (version)
• .claude-plugin/marketplace.json (version AND plugins[0].version)

After writing, re-read all three and confirm they match the new version before proceeding to commit.

7. Commit

Run:

git -C ${AIDP_PLUGIN_ROOT} add <list of files you actually modified>
git -C ${AIDP_PLUGIN_ROOT} commit -m "$(cat <<'EOF'
ai-dp:improve — <one-line summary>

<original $ARGUMENTS, indented or quoted>
EOF
)"

Do NOT include Co-Authored-By: Claude in the message (per project rules).

Stage only the files you modified — never git add . or git add -A.

8. Do NOT push

Print to chat (verbatim — the user asked for this exact reminder block on every improve cycle):

Committed locally on branch <branch>. Push when ready:

git push

Then refresh the plugin in your session:

/plugin marketplace update claude-ai-dev-pipeline-plugin
/reload-plugins

(Other end users will run the same two commands after their next git pull — there is no auto-update.)

9. Live-reload notice

The change is also live in this session already (Claude Code watches plugin dirs). If anything looks off, run /reload-plugins.

Guardrails (recap)

• Refuse when ${AIDP_PLUGIN_ROOT} is under ~/.claude/plugins/cache/.
• Refuse on dirty git tree inside the plugin (unless user explicitly overrides).
• Never edit files outside the plugin tree (no consumer-project files, no ~/.claude/ outside the plugin).
• Never auto-push.
• Never bump MAJOR without explicit confirmation.
• If the requested edit would touch ai-dp:improve's own SKILL.md or its dependencies, double-confirm with AskUserQuestion before writing — there is no recovery if it breaks itself in this session.