Change Ledger¶
Structured record of toolkit changes — the "why" behind the "what".
Read by /vt-c-doc-sync to generate rich What's New content.
2026-04-20¶
SPEC-114: Security Baseline Hardening¶
Discovery: A gap analysis against three sources (team meeting 2026-04-14, Andi's 10-point Confluence checklist, Vectimus 78 Cedar policy rules) revealed that CLAUDE.md instructions ("never force push") were not backed by deny rules, Grep/Glob on credential paths were unblocked while Read was blocked, self-modification of ~/.claude/settings.json was unprotected, knowledge/design projects lacked .env in .gitignore, the pre-commit hook did not scan for secrets, and no .claudeignore template shipped with scaffolds. 41 of 78 Vectimus rules required new native deny rules.
Fix: Expanded configs/security/baseline-settings.json from 5 categories / ~20 rules to 11 categories / ~128 rules (NEW: git safety, code execution, database destructive, infrastructure, self-modification protection, agent governance). Shipped claudeignore-guard.sh PreToolUse hook (Read/Grep/Glob) because Claude Code does NOT natively honor .claudeignore. Added .claudeignore template to scaffold base and .gitleaks.toml to coding scaffold. Added .env* entries to gitignore-base. Extended pre-commit hook to fail-closed on missing secret-scanner and block staged .env files (with .env.example carve-out). Registered 3 new SHA-256 entries in trusted-hooks.yaml and verified during finalize. All fixes for Pass 1 review findings (SEC-1 jq escape, SEC-2 path normalization, SEC-3 credential closures, PERF-1 cache per project_dir+mtime) applied and verified in Pass 2.
Files: configs/security/baseline-settings.json, configs/security/trusted-hooks.yaml, configs/security/SECURITY-CONFIG.md, configs/security/config-snapshot.yaml, plugins/core-standards/scripts/claudeignore-guard.sh, plugins/core-standards/scripts/install-hooks.sh, plugins/core-standards/scripts/pre-commit, plugins/core-standards/skills/bootstrap/SKILL.md, plugins/core-standards/skills/scaffold/SKILL.md, plugins/core-standards/skills/repo-health/SKILL.md, plugins/core-standards/commands/security-scan.md, plugins/core-standards/tests/test-security-baseline.sh, plugins/core-standards/tests/test-claudeignore-guard.sh, plugins/core-standards/tests/test-pre-commit.sh, templates/scaffold/base/.claudeignore, templates/scaffold/base/gitignore-base, templates/scaffold/coding/.gitleaks.toml, docs/security/hardening-guide.md
2026-04-04¶
SPEC-109: Quality Metrics Integration¶
Discovery: The /vt-c-quality-metrics skill existed for tracking coverage, complexity, and duplication but was never automatically invoked during the development workflow. Quality regressions could reach main without anyone noticing because no workflow phase checked metrics automatically.
Fix: Added optional Step 5.8 (Quality Metrics Snapshot) to /vt-c-4-review. Auto-detects coverage tooling (nyc, c8, pytest-cov, go cover, SimpleCov) from project files, runs a coverage snapshot, saves results to specs/[N]-feature/metrics.json, and detects regressions (> 2% line coverage drop). Results are included in the review gate YAML frontmatter and TL;DR summary. Graceful skip for projects without coverage tooling — no warning, no block.
Files: plugins/core-standards/skills/workflow-4-review/SKILL.md
2026-03-24¶
SPEC-095: Workflow Gate Enforcement¶
Discovery: The workflow sequence (activate, plan, build, review, finalize, complete) was advisory only. Gate files (.review-gate.md, .test-gate.md) were gitignored, so no persistent proof existed that review or finalize ran. In the 2026-03-24 session, SPEC-092 and SPEC-094 were merged without review or finalize, causing missing version bumps, changelog entries, and skill count drift.
Fix: Added gate persistence to all 4 phase skills: /vt-c-2-plan writes plan_gate, /vt-c-3-build writes build_gate, /vt-c-4-review writes review_gate, /vt-c-5-finalize writes finalize_gate -- all into specs/[N]-feature/state.yaml as committed YAML. Added Step 2.5 to /vt-c-complete that checks all 4 gates before allowing spec completion, with emergency bypass option that records permanently in state.yaml. Added Rule 16 (Workflow Gate Enforcement) to global ~/.claude/CLAUDE.md.
Files: plugins/core-standards/skills/workflow-2-plan/SKILL.md, plugins/core-standards/skills/workflow-3-build/SKILL.md, plugins/core-standards/skills/workflow-4-review/SKILL.md, plugins/core-standards/skills/workflow-5-finalize/SKILL.md, plugins/core-standards/skills/complete/SKILL.md
SPEC-091: User Manual Update on Spec Completion¶
Discovery: After the initial user manual is generated from the PRD (SPEC-090), the manual becomes stale as features are implemented. Acceptance criteria, technical details, and edge cases discovered during development are not reflected in the manual. Developers must manually update documentation.
Fix: Created /vt-c-user-manual-update skill that auto-generates draft updates to user manual pages when a spec is completed. Integrated with /vt-c-complete as Step 5.5 — after marking a spec complete, it offers to update the corresponding manual page. Added docs_page field support to /vt-c-specs-from-prd so specs know which manual page they correspond to. All auto-generated sections are marked with <!-- DRAFT: review needed --> for human review.
Files: plugins/core-standards/skills/user-manual-update/SKILL.md, plugins/core-standards/skills/complete/SKILL.md, plugins/core-standards/skills/specs-from-prd/SKILL.md, plugins/core-standards/.claude-plugin/skill-symlinks.manifest
2026-03-19¶
SPEC-077: Advanced Diagram Generation — Format Selection + C4 from YAML¶
Discovery: The diagram generation skill (/vt-c-mermaid-diagrams-branded) always output Mermaid regardless of diagram complexity. For diagrams with 15+ elements, Mermaid's Dagre layout engine produces unreadable results with persistent edge crossings. Additionally, there was no way to generate diagrams from structured data — every diagram required manual Mermaid source authoring.
Fix: Added count_elements.py to vt-c-mermaid-diagrams-branded with a three-bucket heuristic: under 10 elements → Mermaid, 10–15 → ask user, over 15 → recommend PlantUML with warning. Created new vt-c-c4-diagram skill with generate_c4.py that generates branded C4 context and container diagrams from c4: YAML frontmatter in system notes. VisiTrans brand colors applied automatically via brand_colors.py.
Files: plugins/core-standards/skills/mermaid-diagrams-branded/scripts/count_elements.py, plugins/core-standards/skills/mermaid-diagrams-branded/scripts/create_diagram.py, plugins/core-standards/skills/c4-diagram/SKILL.md, plugins/core-standards/skills/c4-diagram/scripts/generate_c4.py, plugins/core-standards/skills/c4-diagram/scripts/brand_colors.py
2026-03-17¶
SPEC-058: MCP Config Governance¶
Discovery: MCP server configurations were scattered across three uncoordinated scopes (local, plugin, Anthropic-managed). New team members had to manually discover and configure each server after running setup.sh, creating onboarding friction and configuration drift.
Fix: Added setup_mcp_servers(), migrate_mcp_servers(), and verify_mcp_servers() functions to setup.sh. These auto-configure azure-devops, taskmaster-ai, and github MCP servers via claude mcp add -s user, migrate local-scope duplicates to user scope, and verify health in --verify mode. Added MCP section to /verify-setup command. Created complete MCP server inventory documentation.
Files: scripts/setup.sh, plugins/core-standards/commands/verify-setup.md, docs/reference/mcp-servers.md
2026-03-10¶
SPEC-057: Angular-First Frontend Toolkit Migration¶
Discovery: The toolkit defaulted to React/Next.js for all prototype and frontend skills, but VisiTrans standardized on Angular 21 + PrimeNG + PrimeFlex as the primary frontend stack. Every prototype generation required manual overrides, and no Angular-specific review agent existed.
Fix: Migrated 8 skills to default to Angular 21 with PrimeNG. Created angular-reviewer agent. Extended kieran-typescript-reviewer, julik-frontend-races-reviewer, and accessibility-reviewer with Angular sections. Updated VisiTrans design system with PrimeNG preset and component templates. Added Angular-specific critical patterns (RxJS subscription cleanup, Signal misuse, PrimeNG token enforcement). Preserved React/Next.js content in appendix sections for backward compatibility.
Files: skills/bootstrap/SKILL.md, skills/visitrans-design-system/SKILL.md, skills/kw-prototype/SKILL.md, skills/pd-3-prototype/SKILL.md, skills/pd-6-handoff/SKILL.md, skills/promote/SKILL.md, skills/kw-specs/SKILL.md, agents/review/angular-reviewer.md, agents/review/kieran-typescript-reviewer.md, agents/review/julik-frontend-races-reviewer.md, agents/review/accessibility-reviewer.md, agents/orchestrators/implementation-orchestrator.md, templates/scaffold/coding/critical-patterns.md
2026-03-08¶
SPEC-053: Hook Security Audit¶
Discovery: Repo audit had no way to detect tampered, unauthorized, or rogue hook scripts. Hook files could be modified or added without detection, and no inventory of expected hooks existed.
Fix: Added hook security audit to /vt-c-repo-audit Step 8 with checksum verification, unknown hook detection, network call scanning, and permission checks. Created trusted hooks manifest at configs/security/trusted-hooks.yaml with SHA-256 checksums for all 23 hook scripts. Added automated checksum verification in repo-audit-ci.sh.
Files: skills/repo-audit/SKILL.md, configs/security/trusted-hooks.yaml, scripts/repo-audit-ci.sh, configs/security/SECURITY-CONFIG.md
SPEC-054: Wave-Based Dependency Execution¶
Discovery: Implementation plans executed all tasks sequentially regardless of dependency relationships. Independent tasks that could safely run in parallel were queued behind each other, wasting time and increasing context rot. SpecKit's tasks.md encoded dependency info but no skill used it for parallelization.
Fix: Added wave-based parallel scheduling to /vt-c-activate and /vt-c-3-build that computes dependency waves from task lists and dispatches independent tasks concurrently.
Files: skills/activate/SKILL.md, skills/workflow-3-build/SKILL.md
SPEC-056: Visual Reference Enforcement¶
Discovery: Feature specs lacked a mandatory "Visual Reference" section. The /3-build flow generated components from spec text only, ignoring PRD screenshots and visual mockups. No automated check compared implementation against screenshot references.
Fix: Added visual reference enforcement to the build workflow, ensuring spec templates include a visual reference field and the build phase checks implementation against referenced screenshots.
Files: skills/workflow-3-build/SKILL.md
SPEC-028: Security Review Pipeline¶
Discovery: The toolkit's security review coverage had gaps: no CI/CD automation for PRs, no integration with Anthropic's built-in /security-review command or claude-code-security-review GitHub Action.
Fix: Created structured security review pipeline integrating built-in tooling with the toolkit's review workflow.
Files: skills/security-scan/SKILL.md, .github/workflows/
2026-03-07¶
SPEC-051: Spec-from-Requirements Skill¶
Discovery: Existing spec-creation skills (/pd-5-specs, /kw-specs) both required a formally developed PRD as input. When working in existing projects with informal requirements (documents, notes, verbal descriptions), there was no governed path to create a valid spec.
Fix: Created /vt-c-spec-from-requirements skill that accepts informal requirements and produces a valid spec feeding into the standard /activate → /2-plan → /3-build workflow.
Files: skills/spec-from-requirements/SKILL.md
2026-03-06¶
SPEC-048: Documentation Comprehensive Refresh¶
Discovery: Documentation had drifted from actual toolkit state across five gap categories. docs/whats-new.md stopped at v3.4.0 with three releases undocumented. Symlink manifests were incomplete. Missing guides for security governance, composable skills, and contributing.
Fix: Updated component counts across all sources, completed all symlink manifests, added missing guides, created plugin READMEs, and integrated architecture docs into the MkDocs site.
Files: docs/whats-new.md, docs/index.md, README.md, docs/guides/, plugins/*/README.md
SPEC-049: Workflow Merger Registration¶
Discovery: The constitution v1.0.0 declares a two-workflow model but all orchestrator, skill, command, and documentation files still reflected the original three-workflow model. A spec was needed to track this harmonization work.
Fix: Registered SPEC-049 as a proposed spec to implement the workflow merger so code and documentation match the constitutional declaration.
Files: specs/49-workflow-merger/spec.md, specs/49-workflow-merger/state.yaml
2026-03-05¶
SPEC-032: Agent Worktree Isolation (OXN Airtable)¶
Discovery: Claude Code v2.1.50+ supports isolation: worktree in agent frontmatter but zero of the toolkit's 58 agents used it. Write-capable agents running concurrently could cause branch contamination and merge conflicts.
Fix: Audited all 58 agents and added isolation: worktree to 9 qualified agents. Updated agent creation guidelines with a 4-question isolation decision checklist.
Files: agents/orchestrators/, agents/design/, skills/create-agent-skills/references/agent-frontmatter-fields.md
2026-03-04¶
SPEC-036: GSD Wave-Based Execution¶
Discovery: The toolkit's multi-spec build workflow executed specs sequentially. The GSD framework demonstrated a wave-based parallel execution model where independent tasks run concurrently with fresh context windows.
Fix: Added wave-grouped dashboard to /vt-c-activate, parallel opportunity detection in /vt-c-3-build, and pre-plan /vt-c-shape skill for dependency-aware execution.
Files: skills/activate/SKILL.md, skills/workflow-3-build/SKILL.md, skills/shape/SKILL.md
SPEC-042: Plan-Checker Validation Loop¶
Discovery: The toolkit had no plan validation loop. Plans could have structural issues — missing verification steps, unclear success criteria, dependency gaps — only caught during implementation.
Fix: Added plan-checker validation agent and automated validation loop (up to 3 iterations) in /vt-c-2-plan.
Files: agents/review/plan-checker.md, skills/workflow-2-plan/SKILL.md
SPEC-044: Agent Architecture Patterns Documentation¶
Discovery: The toolkit uses CC 2.1 architectural patterns extensively (skill hooks, sub-agent hooks, context: fork, hook hierarchy) but had no reference documentation explaining the patterns. Authors must reverse-engineer from existing implementations.
Fix: Created reference documentation for CC 2.1 patterns with examples and pitfall guidance.
Files: docs/guides/agent-architecture-patterns.md
SPEC-046: Configuration Drift Audit¶
Discovery: /repo-health checked governance health but did not audit Claude Code configuration files for security drift. No component tracked whether security configurations matched a known-good baseline.
Fix: Extended /vt-c-repo-health with four drift checks: deny rule drift, MCP server drift, blanket MCP enable, and change-aware audit freshness. Added baseline snapshot and drift waivers files.
Files: skills/repo-health/SKILL.md, configs/security/config-snapshot.yaml, configs/security/drift-waivers.yaml, configs/security/SECURITY-CONFIG.md
SPEC-038: Document Placement Strategy¶
Discovery: Git workflow rules forced all changes onto separate branches, but documentation-only changes on separate branches created a visibility problem — users couldn't see newly created docs until merge.
Fix: Docs-only changes stay on the current branch, eliminating visibility gaps.
Files: CLAUDE.md
2026-03-03¶
SPEC-035: Security Hardening Configuration¶
Discovery: The toolkit lacked a systematic security configuration audit. No baseline existed for Claude Code settings hardening, MCP server whitelisting, or permission deny rules.
Fix: Established security baseline at configs/security/baseline-settings.json with deny rules across 5 attack categories. Added security config checks to /vt-c-repo-health and /vt-c-security-scan.
Files: configs/security/baseline-settings.json, configs/security/SECURITY-CONFIG.md, skills/repo-health/SKILL.md, skills/security-scan/SKILL.md
SPEC-037: CWP Pre-PR Automated Checks¶
Discovery: CWP PRs were created with unchecked test-plan items that were fully automatable. During CWP-01 (55 files), a PR shipped with 4 unchecked items including unverified MkDocs build and unvalidated YAML frontmatter.
Fix: Added automated pre-PR validation for CWP lifecycle with must-pass checks (MkDocs build, YAML frontmatter, no broken wikilinks) integrated into /vt-i-cwp.
Files: plugins/ims/skills/ims-cwp/SKILL.md
SPEC-039: UFI Country Enrichment Pipeline¶
Discovery: The UFI participant scraper extracted country data but the sync pipeline never wrote it to Airtable despite the field existing on Contact and Company tables with 85 pre-existing country records.
Fix: Added country enrichment to /vt-u-sync for contacts and companies with confidence scoring.
Files: plugins/ufi/skills/
SPEC-029: Skill Permission Governance¶
Discovery: The toolkit suffered from "approval fatigue" — during long sessions, Claude frequently paused to request tool approval or ask "Should I continue?", breaking flow. No mechanism existed for skill-to-agent permission binding or autonomy delegation.
Fix: Added agent: frontmatter field for binding skills to pre-authorized agents, allowed-tools documentation for tool pre-authorization, and autonomy-continue.sh stop hook with session-isolated counters. Created three agent templates: ims-writer, toolkit-developer, docs-pipeline.
Files: skills/skill-creator/SKILL.md, hooks/autonomy-continue.sh, agents/templates/
2026-03-02¶
SPEC-030: Intelligent Skill Activation¶
Discovery: Skill activation relied entirely on explicit /skill-name invocation. After context compaction, skill awareness was lost. No intent-based activation existed to suggest relevant skills based on user actions.
Fix: Added three-layer skill amnesia mitigation (CLAUDE.md inventory, PreCompact hook, post-compaction recovery), path-match.sh utility for file-path filtering, and intent-skill-matcher.sh for intent-based skill suggestion.
Files: scripts/precompact-skill-inventory.sh, scripts/postcompact-recovery.sh, hooks/path-match.sh, hooks/intent-skill-matcher.sh
SPEC-031: Skill Quality Assurance¶
Discovery: Skills were deployed untested — the skill-creator had no validation step. Reviews conflated spec compliance with code quality: 6 parallel reviewers checked "is it well-written?" but none checked "does it do what was intended?".
Fix: Added pressure-test validation to skill-creator and spec-compliance-reviewer agent as a prerequisite to code quality checks in /vt-c-4-review.
Files: skills/skill-creator/SKILL.md, agents/review/spec-compliance-reviewer.md, skills/workflow-4-review/SKILL.md
2026-03-01¶
SPEC-034: Beads Activation¶
Discovery: The toolkit had a dead gap in persistent work-item tracking. Beads integration code existed in 12 files across 6 workflow phases but was never initialized. File-todos existed but were never deployed.
Fix: Activated Beads distributed issue tracker, replacing file-todos for persistent work-item tracking.
Files: skills/workflow-0-start/SKILL.md, skills/workflow-1-bootstrap/SKILL.md, skills/workflow-3-build/SKILL.md
2026-02-28¶
SPEC-026: Inbox File Routing¶
Discovery: The product design inbox (00-Inbox/) accumulated files that had already been fully processed through the pd- iteration loop. After processing, files remained indefinitely, making it impossible to tell at a glance whether pending work existed.
Fix: Added file routing that moves processed inbox items to an archive directory after completion, reflecting processing status in the filesystem.
Files:* skills/pd-inbox-scan/SKILL.md
2026-02-26¶
FIX: Documentation Synchronization¶
Discovery: Documentation had drifted significantly from actual toolkit state. Component counts were wrong across 6 sources (README, docs/index, core-standards.md, plugin.json, macros.py — none agreed with filesystem). README still said "Three Workflows" despite v3.0.0 harmonizing to two. Version shown as 3.0.0 (actual: 3.2.0). <function define_env.<locals>.command_count at 0x7f99ff9ee2a0> macro used but never defined. No What's New page existed. Three docs pages were missing descriptions of recent SPEC features (version gate, auto-fix loop, advanced skill frontmatter).
Fix: Created /vt-c-doc-sync skill for ongoing drift detection. Applied mechanical fixes to all count/version/terminology sources. Created What's New page and change ledger. Added version gate docs to 5-finalize.md, auto-fix loop docs to 4-review.md, and advanced frontmatter docs to creating-skills.md.
Files: README.md, docs/index.md, docs/plugins/core-standards.md, docs/whats-new.md, docs/change-ledger.md, scripts/docs-gen/macros.py, mkdocs.yml, docs/workflows/development/vt-c-4-review.md, docs/workflows/development/vt-c-5-finalize.md, docs/guides/creating-skills.md
SPEC-024: Review Auto-Fix Loop¶
Discovery: During code reviews, /vt-c-4-review often returned GO WITH CAUTION with medium findings that were mechanically fixable (naming, imports, simplification). The workflow paused to ask the user whether to fix, adding friction to an automatable step. This pattern repeated across multiple specs.
Fix: Added auto-fix loop to /vt-c-4-review Step 4.5 that classifies findings as [AUTO-FIXABLE] or [HUMAN-REQUIRED], applies mechanical fixes up to 2 iterations, and only surfaces non-automatable findings to the user.
Files: skills/workflow-4-review/SKILL.md
SPEC-023: Finalize Gate Version Enforcement¶
Discovery: Releases could proceed without version bumps or changelog entries, causing silent version drift between what was finalized and what documentation reflected. Multiple releases landed without corresponding CHANGELOG updates.
Fix: Added check-finalize-versions.sh script that blocks /vt-c-5-finalize Step 0c when a version bump or changelog entry is missing for changed plugins. Reads registry.json and compares against last-finalized state.
Files: skills/workflow-5-finalize/SKILL.md, scripts/check-finalize-versions.sh
SPEC-022: Session Start Notifications¶
Discovery: Users had no visibility into plugin version changes between sessions. New features, breaking changes, and bug fixes went unnoticed, leading to confusion when workflows behaved differently than expected.
Fix: Added session-start.sh hook and check-plugin-versions.sh script. On session start, compares registry.json versions against a user-local last-seen state file. Shows MAJOR/MINOR/PATCH diffs with top changelog entries for context.
Files: scripts/session-start.sh, scripts/check-plugin-versions.sh, hooks/hooks.json
2026-02-25¶
SPEC-021: IMS Plugin Extraction¶
Discovery: The core-standards plugin had grown to include IMS (Information Security, Data Protection, Quality Management) agents and skills that were only relevant to compliance workflows. This bloated the base install and mixed concerns.
Fix: Extracted 6 IMS agents and 6 IMS skills into an independent ims plugin with its own .claude-plugin/ metadata, CHANGELOG, and dependency on core-standards. Reduced core-standards component counts accordingly.
Files: plugins/ims/, plugins/registry.json, plugins/core-standards/CHANGELOG.md
SPEC-020: Plugin Versioning Foundation¶
Discovery: The toolkit had no formal versioning system. Plugin versions were tracked ad-hoc, CHANGELOGs were optional, and there was no mechanism to detect or communicate version changes to users.
Fix: Established semantic versioning for all plugins via registry.json as single source of truth. Added plugin versioning guide, CHANGELOG requirements in creating-plugins guide, and version sync rules.
Files: plugins/registry.json, docs/guides/plugin-versioning.md, docs/plugins/creating-plugins.md
2026-02-24¶
FIX: Gate Files Reverted on Branch Switch¶
Discovery: During SPEC-018 finalization, /vt-c-5-finalize failed 4 times because .review-gate.md and .test-gate.md contained stale data from previous branches. Gate files reverted to old branch values on every git checkout because they were tracked by git despite being ephemeral workflow state.
Fix: Added .review-gate.md, .test-gate.md, and .claude-checkpoint.md to .gitignore. Untracked the existing files so they persist locally without being committed.
Files: .gitignore, skills/vt-c-phase-checkpoint/SKILL.md
2026-02-14¶
BREAKING: Multi-Plugin Architecture (v3.0.0)¶
Discovery: The monolithic plugin structure couldn't support department-specific tooling (finance, IMS) without bloating the core install. All components lived in a single .claude-plugin/ directory with no separation of concerns.
Fix: Introduced multi-plugin architecture with per-plugin .claude-plugin/ directories, plugins/registry.json as version authority, and setup.sh --plugins flag for selective installation. Harmonized architecture from three-workflow to two-workflow per constitution v1.0.0.
Files: plugins/registry.json, plugins/core-standards/.claude-plugin/, scripts/setup.sh