Contributing to the Toolkit

How consuming projects submit improvements back to the toolkit.

The improvement pipeline

Every project using the toolkit generates insights — bugs found, patterns discovered, workflow friction identified. The intake pipeline captures these insights and feeds them back into the toolkit as durable improvements.

Session journal  →  Intake proposal  →  Toolkit review  →  SPEC  →  Implementation

1. Capture — use /vt-c-journal during work to record decisions, problems, and insights
2. Propose — submit an intake proposal describing the improvement
3. Review — the toolkit maintainer evaluates proposals via /vt-c-toolkit-review
4. Specify — accepted proposals become SPECs with acceptance criteria
5. Implement — SPECs flow through the standard development workflow

Submitting an intake proposal

Place a markdown file in the appropriate intake directory:

Source	Directory
Project experience	intake/pending/from-projects/
Root cause analysis	intake/pending/from-rca/
External research	intake/pending/from-research/

Required YAML frontmatter

Every proposal must have this frontmatter:

---
type: procedure-improvement  # or: new-skill, bug-report, pattern-promotion
date: 2026-03-05
source: P01-Notfallsani-Lernsystem
source_path: docs/toolkit-proposals/improve-error-handling.md
target_skill: defense-in-depth
severity: medium  # critical, high, medium, low
category: quality
toolkit_proposal_status: pending
tags: [error-handling, validation]
---

Body content

After the frontmatter, describe:

1. Problem — what went wrong or what is missing (evidence-based)
2. Proposed solution — concrete suggestion for improvement
3. Impact — which projects or workflows benefit
4. References — journal entries, error logs, or session transcripts

What makes a good proposal

• Problem-first — start with what happened, not what you want
• Evidence-based — include file paths, error messages, or session context
• Scoped — one proposal per improvement (not a grab-bag of ideas)
• Actionable — the reader can understand what to change without additional context

Proposal lifecycle

Status	Meaning
pending	Submitted, awaiting review
under-review	Being evaluated by toolkit maintainer
accepted	Approved, will become a SPEC
rejected	Not accepted (reason documented)
completed	Implemented and deployed

Failure-to-rule pipeline

Every agent mistake should become a rule that prevents the class of mistake from recurring. This is the systematic process:

Agent makes mistake  →  Identify root cause  →  Write rule  →  Add to CLAUDE.md/SKILL.md

When to trigger

At the end of every session, ask yourself: - Did the agent make a mistake that wasted time? - Did the agent misunderstand an instruction? - Did the agent produce output that needed significant correction?

How to convert a failure into a rule

1. Describe the failure: What happened? What was expected?
2. Identify the class: Is this a one-off or a pattern? (e.g., "agent always formats dates wrong" → date formatting rule)
3. Write the prohibition with rationale: Never X — because Y (the rationale lets agents generalize)
4. Choose the scope: CLAUDE.md (project-wide), SKILL.md (skill-specific), or agent definition (agent-specific)
5. Apply via /vt-c-claudemd-evolve: This skill updates CLAUDE.md with new rules

Integration with session journal

When using /vt-c-journal, tag failures with #agent-mistake so they can be batch-processed into rules during consolidation.

Project registration

Projects must be registered in intake/projects.yaml to participate in the intake pipeline. Register with /vt-c-project-register or add an entry manually:

- path: /Users/team/project-name
  name: project-name
  type: coding  # or: mixed, knowledge
  registered: 2026-03-05

Registered projects are scanned by /vt-c-project-sync for journal entries and toolkit proposals.