Claude Code rejects `defaultModel` in plugin.json and `model` in agent
frontmatter with "Unrecognized key" validation error.
Removed:
- defaultModel from 6 plugin.json files
- model from 7 agent frontmatter files
- docs/MODEL-RECOMMENDATIONS.md (deleted)
- Model config sections from CONFIGURATION.md and CLAUDE.md
- Model validation from validate-marketplace.sh
This reverts Sprint 7 (v5.4.0) multi-model feature that was never
supported by Claude Code's plugin schema.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
clear-cache.md and suggest-version.md were missing the required YAML
frontmatter with description field. This caused Claude Code to skip
loading the entire projman plugin's commands.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
BREAKING: Removes automatic venv management that was causing session failures
Changes:
- Delete scripts/venv-repair.sh (was deleting and recreating venvs)
- Remove auto-repair code from projman/hooks/startup-check.sh
- Remove venv-repair call from scripts/post-update.sh
- Remove rm -rf .venv instructions from docs/UPDATING.md and CONFIGURATION.md
- Update docs/CANONICAL-PATHS.md to remove venv-repair.sh reference
Additionally:
- Add Pre-Change Protocol to CLAUDE.md (mandatory dependency check before edits)
- Add Pre-Change Protocol enforcement to claude-config-maintainer plugin
- Add Development Context section to CLAUDE.md clarifying which plugins are
used in this project vs only being developed
- Reorganize commands table to separate relevant vs non-relevant commands
The venv auto-repair was the root cause of repeated MCP server failures,
requiring manual setup.sh runs after every session start.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The MCP consolidation commit (afd4c44) deleted plugin-level .mcp.json files
but left references to them in plugin.json and marketplace.json. This caused
7 plugins to fail loading (projman, pr-review, cmdb-assistant, data-platform,
viz-platform, contract-validator, and indirectly git-flow/clarity-assist).
Changes:
- Remove mcpServers field from 6 plugin.json files (file no longer exists)
- Remove mcpServers field from 6 marketplace.json entries
- Add file reference validation to validate-marketplace.sh:
- Validates mcpServers references point to existing files
- Validates hooks references point to existing files
- Validates commands references point to existing paths
- Add pre-commit hook (.git/hooks/pre-commit) to enforce validation
The validation script will now FAIL if any config file references a
non-existent file, preventing this class of bug from happening again.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Move all MCP server declarations from individual plugin .mcp.json files
to a single .mcp.json at the marketplace root. This fixes MCP loading
failures where only one plugin's MCP would load.
- Add .mcp.json at marketplace root with all 5 servers
- Remove plugin-level .mcp.json files (projman, pr-review, cmdb-assistant,
data-platform, viz-platform, contract-validator)
- Update CLAUDE.md to reflect new architecture
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The startup-check.sh hook was clearing ~/.claude/plugins/cache/ at every
session start, which was aggressive and potentially disruptive. Cache
clearing is now a manual operation via the new /clear-cache command.
Changes:
- Remove automatic cache clearing from startup-check.sh
- Add /clear-cache command for manual cache clearing when needed
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove all output by default to prevent workflow interruption
- Queue changes silently to .doc-guardian-queue
- Add file+type deduplication (same file won't be queued twice)
- Add DOC_GUARDIAN_VERBOSE=1 env var for opt-in notifications
- Users run /doc-sync or /doc-audit to process queue
Fixes#312 (partial - addresses issues 1, 2, 3)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add defaultModel: sonnet to all plugin manifests that have agents,
establishing the plugin-level default in the model inheritance chain.
Version bumps:
- projman: 3.2.0 → 3.3.0 (minor: new feature)
- pr-review: 1.0.0 → 1.1.0 (minor: new feature)
- data-platform: 1.0.0 → 1.1.0 (minor: new feature)
- viz-platform: 1.0.0 → 1.1.0 (minor: new feature)
- code-sentinel: 1.0.0 → 1.0.1 (patch: config addition)
- contract-validator: 1.0.0 → 1.1.0 (minor: new feature)
Fixes#305
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Changed from nested object format to array format to fix
"PreToolUse:Bash hook error" with no message.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
PRs merged to development don't trigger Gitea's auto-close feature
(only merges to main do). Added warnings in Steps 13 and 15 to remind
about mandatory manual issue closing after PR merge.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds early detection of version drift between README.md, marketplace.json,
and CHANGELOG.md at session start. When versions don't match, displays
a warning and suggests running /suggest-version to analyze and fix.
This addresses acceptance criteria #4 from issue #290:
- [x] SessionStart warns about version drift
Remaining criteria for future PRs:
- [ ] Version mismatch detected before commit (PreToolUse hook)
- [ ] /sprint-close includes version bump step (enforcement)
- [ ] Release workflow works with protected branches (PR creation)
Partial fix for #290
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The PostToolUse hook was causing workflow interruptions because:
1. Actionable language ("update needed") triggered Claude to seek confirmation
2. Rapid edits (4+ in sequence) generated multiple notifications
Changes:
- Message changed from "update needed" to "drift queued" (passive, informational)
- Added 5-second debouncing: same-type edits within window are silently queued
- Added queue clearing step to doc-sync.md command
Note: Issue #287 also mentions URL restriction behavior, but this was not
found in the current codebase - may have been a different component or
already fixed. Marking as partial fix.
Fixes#287
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Addresses issue #278 - sprint-diagram command not discoverable after Sprint 4.
Root cause: Claude Code discovers skills at session start. Commands added
during a session are NOT discoverable until restart.
Prevention: Added step 7 "New Command Verification" to sprint-close workflow:
- Reminds about session restart requirement
- Creates follow-up verification task
- Explains why this happens
Lesson learned created: lessons/patterns/sprint-4---new-commands-not-discoverable-until-session-restart
Closes#278
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sprint-plan approval workflow:
- Request explicit approval after creating issues
- Present scope summary (branches, files, dependencies)
- User must type "approve sprint N" to authorize
- Record approval in milestone description with timestamp
Sprint-start verification:
- Check milestone for "## Sprint Approval" section
- If missing, STOP and direct to /sprint-plan
- Extract approved scope (branches, files)
- Enforce scope during execution
Orchestrator scope enforcement:
- Verify approval before any execution
- Check each operation against approved scope
- Operations outside scope require re-approval
This separates planning (review) from execution (action),
preventing agents from executing without explicit user consent.
Closes#233
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Executor checkpointing:
- Standard checkpoint comment format with branch, commit, phase
- Files modified with status (created, modified)
- Completed and pending steps tracking
- State notes for resumption context
- Save checkpoint after major steps, before stopping
Orchestrator resume detection:
- Scan issue comments for "## Checkpoint" markers
- Offer resume options: resume, start fresh, review details
- Verify branch exists and files match before resuming
- Dispatch executor with checkpoint context
Sprint-start integration:
- Checkpoint detection as first workflow step
- Resume flow documentation with example
- Checkpoint format specification
This enables resuming work after:
- Budget exhaustion (100 tool call limit)
- Agent failure/circuit breaker
- Manual interruption
- Session timeout
Closes#237
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add pre-dispatch conflict detection:
- Analyze target files for each task before parallel dispatch
- Check for file overlap between tasks in same batch
- If overlap detected, sequentialize those specific tasks
- Example analysis showing conflict detection workflow
Branch isolation protocol:
- Each task MUST have its own branch
- Never have two agents work on the same branch
- Sequential merge after completion (not simultaneous)
- Handle merge conflicts by stopping second task
Conflict resolution rules:
- Same file → MUST sequentialize
- Same directory → Usually safe, review
- Shared config → Sequentialize
- Shared test fixture → Sequentialize or assign different files
This prevents parallel agents from modifying the same files
and causing git merge conflicts.
Closes#234
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add structured progress comment format for agents:
- Standard format with Status, Phase, Tool Calls budget
- Completed/In-Progress/Blockers/Next sections
- Clear examples for starting, blocked, and failed states
- Guidance on when to post (every 20-30 tool calls)
Update sprint-status.md:
- Document how to parse progress comments
- Show enhanced in-progress display with tool call tracking
- Add progress comment detection to blocker analysis
This enables users to see:
- Real-time agent progress
- Tool call budget consumption
- Current phase and step
- Blockers as they occur
Closes#232
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add Status/In-Progress, Status/Blocked, Status/Failed, Status/Deferred labels
- Update orchestrator.md with Status Label Management section
- Update executor.md with honest Status Reporting requirements
- Update labels-reference.md with Status detection guidelines
Status labels enable accurate tracking:
- In-Progress: Work actively being done
- Blocked: Waiting for dependency/external factor
- Failed: Attempted but couldn't complete
- Deferred: Moved to future sprint
Agents must report honestly - never say "completed" when blocked/failed.
Closes#235
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implements PostToolUse hook to warn about breaking interface changes:
- Detects changes to plugin.json, hooks.json, .mcp.json, agents/*.md
- Compares with git HEAD to find removed/changed elements
- Warns on: removed hooks, changed matchers, removed MCP servers
- Warns on: plugin name changes, major version bumps
- Non-blocking, configurable via CONTRACT_VALIDATOR_BREAKING_WARN
Depends on #229 (SessionStart auto-validate infrastructure).
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implements smart SessionStart hook for plugin validation:
- Validates plugin contracts only when files change (smart mode)
- Caches file hashes to avoid redundant checks
- Non-blocking warnings for compatibility issues
- Configurable via CONTRACT_VALIDATOR_AUTO_CHECK
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implements UserPromptSubmit hook to detect vague prompts:
- Checks for short prompts without context
- Detects ambiguous phrases ("fix it", "help me with")
- Suggests /clarity-assist when beneficial
- Non-blocking, configurable via CLARITY_ASSIST_AUTO_SUGGEST
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implements PostToolUse hook to warn about potentially breaking schema changes:
- DROP COLUMN/TABLE/INDEX detection
- Column type changes (ALTER TYPE, MODIFY COLUMN)
- NOT NULL constraint additions
- RENAME operations
- ORM model field removals
Non-blocking - outputs warnings only.
Configurable via DATA_PLATFORM_SCHEMA_WARN env var.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The Claude plugin cache at ~/.claude/plugins/cache/leo-claude-mktplace/
holds versioned copies of .mcp.json files. When we update .mcp.json
to use run.sh instead of direct python paths, the cache retains old
versions, causing MCP servers to fail.
Now post-update.sh clears this cache, forcing Claude to read fresh
configs from the installed marketplace on next session start.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replace direct python path in .mcp.json with run.sh wrapper scripts
that automatically locate the venv in cache or local directory.
Problem: .venv symlinks are gitignored, causing them to be wiped on
every git operation. The SessionStart hook should recreate them but
this was unreliable, leading to repeated MCP server failures.
Solution: run.sh scripts that:
- First check ~/.cache/claude-mcp-venvs/leo-claude-mktplace/{server}/.venv
- Fallback to local .venv if exists
- Exit with helpful error if neither found
This eliminates dependency on symlinks entirely - the scripts are
tracked in git and will always be present after clone/pull/update.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Problem:
- Venvs in marketplace directory got deleted on every update
- Users had to manually run setup.sh and wait for full pip install
- This caused MCP servers to fail until manually fixed
Solution:
- Store venvs in external cache (~/.cache/claude-mcp-venvs/)
- Auto-repair symlinks via SessionStart hook (instant operation)
- Only run pip install on first use or when requirements change
Architecture:
Cache (runtime) → Marketplaces → External venv cache
The chain of symlinks ensures all three locations work:
1. ~/.claude/plugins/cache/.../mcp-servers/* (runtime)
2. ~/.claude/plugins/marketplaces/.../mcp-servers/* (install)
3. ~/.cache/claude-mcp-venvs/* (persistent venvs)
Performance:
- First install: ~2-3 min (unchanged)
- After marketplace update: 0.03 sec (was 2-3 min)
Files:
- scripts/venv-repair.sh: Fast symlink restoration for hooks
- scripts/setup-venvs.sh: Full setup with external cache
- plugins/projman/hooks/startup-check.sh: Auto-repair on session start
- .gitignore: Ignore .venv symlinks
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add /initial-setup command for contract-validator plugin
- Add contract-validator section to README.md (NEW in v5.0.0)
- Update data-platform version tag: *NEW* -> *NEW in v4.0.0*
- Update viz-platform version tag: *NEW* -> *NEW in v4.0.0*
- Add Contract Validator MCP Server section to README.md
- Add contract-validator to test commands table and repo structure
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add 2 autonomous agents:
- full-validation: Complete cross-plugin compatibility validation
triggered by /validate-contracts command
- agent-check: Single agent definition validation triggered
by /check-agent command
Each agent documents capabilities, workflow, validation rules,
and example interactions.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add 3 user-facing commands:
- /validate-contracts: Full marketplace compatibility validation
- /check-agent: Validate single agent definition
- /list-interfaces: Show plugin interfaces summary
Each command documents usage, workflow, parameters, and available
MCP tools for implementation.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
