tomevault-io Add Context Commits
This skill guides you through creating new [CONTEXT] commits to document project knowledge and updating CLAUDE.md to reference them.
When to Use
Use this skill when:
- Adding new project requirements or specifications
- Documenting a new workflow or process
- Recording architectural decisions
- Adding coding standards or conventions
- The user requests to "add context" or "document workflow"
Steps to Add Context
1. Determine Context Type
Ask the user what type of context they want to add:
- Requirements/Specifications: Project goals, features, technical requirements
- Workflows: Development processes, TDD practices, deployment procedures
- Architecture: Design decisions, patterns, trade-offs, technical choices
- Standards: Coding conventions, style guides, best practices
- Domain Knowledge: Business logic, domain concepts, terminology
2. Create the [CONTEXT] Commit
Create an empty commit with [CONTEXT] prefix and detailed message:
git commit --allow-empty -m "[CONTEXT] Brief title here
Detailed explanation of the context.
## Section 1
- Point 1
- Point 2
## Section 2
- More details
- Guidelines
- Examples
## Notes
Additional information or rationale.
"
Important: Use --allow-empty to create documentation commits without file changes.
3. Get the Commit Hash
Retrieve the hash of the newly created commit:
git log -1 --format=%H
Or for abbreviated hash:
git log -1 --format=%h
4. Update CLAUDE.md
Read the current CLAUDE.md and add the new commit reference:
# Read current CLAUDE.md
cat CLAUDE.md
Add a new line to the context list with format:
N. [commit-hash] Brief description
Maintain numbering sequence and keep context-progress as the last item.
5. Verify the Addition
Confirm the new context is accessible:
# Read the new context commit
git log [new-commit-hash] -1 --format=%B
# Verify CLAUDE.md updated
cat CLAUDE.md
Best Practices
Context Commit Guidelines
- Use [CONTEXT] Prefix: Always start the commit message with
[CONTEXT] - Descriptive Titles: First line should briefly summarize the context topic
- Structured Content: Use markdown sections (##) to organize information
- Self-Contained: Each commit should be complete and understandable on its own
- Immutable: Once created, context commits should not be amended (create new ones instead)
CLAUDE.md Organization
- Logical Ordering: Group related context commits together
- Brief Descriptions: Keep the reference line concise but clear
- Progress Last: Always keep context-progress branch as the last reference
- Session Instructions: Maintain clear SESSION INITIALIZATION section
When to Create New vs Update Existing
Create New Context Commit When:
- Adding completely new topic or workflow
- Context represents a significant change in approach
- Want to preserve history of decision changes
Update Existing (via new commit):
- Refining or expanding existing context
- Correcting outdated information
- Evolution of a process or pattern
Example Context Commit Types
Requirements Example
git commit --allow-empty -m "[CONTEXT] API Authentication Requirements
The application must support multiple authentication methods:
## Supported Methods
- OAuth 2.0 (Google, GitHub)
- JWT tokens for API access
- API keys for service-to-service
## Security Requirements
- All tokens must expire within 24 hours
- Refresh tokens valid for 30 days
- Rate limiting: 1000 requests/hour per user
## Implementation Notes
- Use industry-standard libraries
- Store tokens securely (encrypted at rest)
- Implement token rotation
"
Workflow Example
git commit --allow-empty -m "[CONTEXT] Code Review Process
All code changes must follow this review process:
## Steps
1. Create feature branch from main
2. Implement with tests (TDD required)
3. Self-review checklist before PR
4. Submit PR with description and test evidence
5. Address review feedback
6. Require 2 approvals before merge
7. Squash commits on merge
## Review Focus Areas
- Test coverage (minimum 80%)
- Code clarity and documentation
- Performance implications
- Security considerations
## Timeline
- Reviews should complete within 24 hours
- PRs open longer than 3 days need re-review
"
Architecture Example
git commit --allow-empty -m "[CONTEXT] Database Architecture Decision
We chose PostgreSQL with the following schema design:
## Decision Rationale
- Need for complex queries and joins
- ACID compliance required
- Strong typing and constraints
- JSON support for flexible data
## Schema Pattern
- Normalized relational design for core entities
- JSONB columns for extensible metadata
- Separate schemas for multi-tenancy
## Trade-offs
- More complex migrations vs MongoDB flexibility
- Better data integrity vs NoSQL scalability
- Chose consistency over eventual consistency
"
After Adding Context
Remind the user that:
- New context is immediately available via git log
- Claude will see it on next session (reads CLAUDE.md)
- Context commits are immutable - create new ones to update
- Push commits to share with team
Converted and distributed by TomeVault — claim your Tome and manage your conversions.