commit 622d2c968d76782c580bedec72240ae5ce4973e0 Author: Zhongwei Li Date: Sat Nov 29 18:17:25 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..83d277a --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,19 @@ +{ + "name": "context-toolkit", + "description": "Implements the CONTEXT.md workflow system for managing human-authored context and agent-ready briefings in Claude Code", + "version": "1.0.0", + "author": { + "name": "Daniel Rosehill", + "email": "public@danielrosehill.com", + "url": "https://danielrosehill.com" + }, + "agents": [ + "./agents" + ], + "commands": [ + "./commands" + ], + "hooks": [ + "./hooks" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..8fc8bf9 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# context-toolkit + +Implements the CONTEXT.md workflow system for managing human-authored context and agent-ready briefings in Claude Code diff --git a/agents/context-converter.json b/agents/context-converter.json new file mode 100644 index 0000000..e0e448f --- /dev/null +++ b/agents/context-converter.json @@ -0,0 +1,8 @@ +{ + "name": "context-converter", + "description": "Specialized agent for converting between human context (CONTEXT.md) and agent briefings (CLAUDE.md)", + "systemPrompt": "You are a specialized agent focused on context conversion and management within the CONTEXT.md workflow system.\n\nYour role is to:\n1. Convert human-friendly, conversational context (CONTEXT.md) into structured agent briefings (CLAUDE.md)\n2. Extract information from agent briefings and incorporate it back into human context\n3. Maintain consistency between both files\n4. Preserve the distinct character of each file type\n\nWhen converting CONTEXT.md to CLAUDE.md:\n- Extract actionable requirements and technical specifications\n- Create clear, structured sections (Overview, Requirements, Implementation Guidance, etc.)\n- Remove conversational filler while preserving essential meaning\n- Maintain precision and clarity for agent consumption\n- Add a reference section pointing back to CONTEXT.md for deeper context\n\nWhen converting CLAUDE.md to CONTEXT.md:\n- Expand terse instructions into narrative explanations\n- Add context about the 'why' behind decisions\n- Maintain conversational, human-friendly tone\n- Integrate naturally with existing context content\n- Preserve technical details and requirements\n\nKey principles:\n- CONTEXT.md is expressive, detailed, human-friendly\n- CLAUDE.md is structured, concise, agent-optimized\n- Both files serve different but complementary purposes\n- Keep them synchronized but respect their different formats\n\nUse the Read tool to examine files before making changes. Use the Edit tool for targeted updates or Write tool for complete rewrites when appropriate.", + "tools": ["Read", "Edit", "Write", "Glob", "Grep"], + "temperature": 0.3, + "maxTokens": 4096 +} diff --git a/agents/context-manager.json b/agents/context-manager.json new file mode 100644 index 0000000..b25efde --- /dev/null +++ b/agents/context-manager.json @@ -0,0 +1,8 @@ +{ + "name": "context-manager", + "description": "Specialized agent for managing, organizing, and maintaining repository context files", + "systemPrompt": "You are a specialized agent focused on context file management and organization within the CONTEXT.md workflow system.\n\nYour role is to:\n1. Add new information to the context pool (CONTEXT.md or context-data/)\n2. Remove outdated or incorrect information\n3. Reorganize and restructure context files\n4. Chunk large CONTEXT.md files into organized topic-based files\n5. Maintain consistency and quality across all context files\n\nWhen adding new context:\n- Integrate naturally with existing content\n- Avoid duplication\n- Maintain narrative flow and readability\n- Use appropriate section headers\n- Update CLAUDE.md to reflect new information\n\nWhen removing context:\n- Ensure clean removal without breaking document flow\n- Update cross-references in other files\n- Sync changes to CLAUDE.md\n- Delete empty files if using chunked structure\n\nWhen chunking context:\n- Analyze content to identify natural topic boundaries\n- Propose logical organization structure\n- Create topic-based files with descriptive names\n- Build an index file (context-data/README.md)\n- Update CLAUDE.md to reference new structure\n- Preserve original CONTEXT.md as backup\n\nWhen managing chunked context:\n- Maintain consistent formatting across files\n- Ensure each chunk is cohesive and focused\n- Keep cross-references valid\n- Update index when adding new files\n\nKey principles:\n- Context should be well-organized and easy to navigate\n- Preserve the human-friendly, narrative style\n- Keep CONTEXT.md and CLAUDE.md synchronized\n- Avoid over-chunking (files should have substantial content)\n- Use clear, descriptive filenames (kebab-case)\n\nUse Read, Edit, Write, Glob tools as needed for file operations.", + "tools": ["Read", "Edit", "Write", "Glob", "Grep", "Bash"], + "temperature": 0.3, + "maxTokens": 4096 +} diff --git a/commands/add-to-context.md b/commands/add-to-context.md new file mode 100644 index 0000000..de32243 --- /dev/null +++ b/commands/add-to-context.md @@ -0,0 +1,43 @@ +--- +description: Add new contextual information to the repository's context pool +--- + +I would like to add new contextual information to this repository. + +The context data is gathered in CONTEXT.md (or in a context-data/ directory if chunked into multiple files). + +I will provide new context that adds information to the context pool. + +After I provide this information, execute these tasks in order: + +## Task 1: Update the Context Pool + +Add the new information to the appropriate location: + +**If using CONTEXT.md:** +- Integrate the new information into CONTEXT.md +- Add appropriate section headers if introducing new topics +- Maintain the narrative, conversational style +- Ensure logical organization and flow +- Avoid duplication with existing content + +**If using context-data/ directory:** +- Determine the most appropriate file based on topic/category +- Create a new file if the information represents a new category +- Use descriptive filenames (e.g., `user-requirements.md`, `technical-constraints.md`) +- Maintain consistent formatting across files + +## Task 2: Update CLAUDE.md + +Review and update CLAUDE.md to ensure it remains accurate and aligned with the expanded context: + +1. **Check for new requirements**: If the new context introduces requirements, add them to CLAUDE.md +2. **Update project overview**: Reflect any changes to project scope or vision +3. **Add implementation guidance**: Include any new technical constraints or decisions +4. **Maintain consistency**: Ensure CLAUDE.md accurately reflects the expanded context pool + +The goal is to keep both the human context (CONTEXT.md) and agent briefing (CLAUDE.md) synchronized and accurate. + +## User Input Required + +Please provide the new context you'd like to add. I'll handle the integration and updates. diff --git a/commands/chunk-repo-context.md b/commands/chunk-repo-context.md new file mode 100644 index 0000000..ab64d0a --- /dev/null +++ b/commands/chunk-repo-context.md @@ -0,0 +1,79 @@ +--- +description: Split CONTEXT.md into organized chunks in context-data/ directory +--- + +This repository currently uses a single CONTEXT.md file for storing project context. + +As projects grow, a single context file can become unwieldy. This command will help split CONTEXT.md into organized, topic-based chunks stored in a context-data/ directory. + +Execute these tasks in sequence: + +## Task 1: Analyze Current Context + +Read and analyze the current CONTEXT.md to identify: +- Distinct topics and themes +- Natural section boundaries +- Logical groupings of information +- Information that could be categorized + +## Task 2: Propose Chunking Structure + +Based on the analysis, propose a chunking structure with: +- Suggested topic-based filenames (e.g., `project-vision.md`, `technical-requirements.md`, `user-stories.md`) +- What content would go in each file +- Rationale for the proposed organization + +Present this structure to the user for approval before proceeding. + +## Task 3: Create context-data/ Directory Structure + +After user approval: +1. Create `context-data/` directory in repository root +2. Create individual markdown files based on approved structure +3. Distribute content from CONTEXT.md into appropriate files +4. Ensure each file has: + - Clear descriptive filename + - Appropriate section headers + - Consistent formatting + - Preserved narrative style + +## Task 4: Create Context Index + +Create `context-data/README.md` that serves as an index: +- List all context files with brief descriptions +- Explain the organization structure +- Provide guidance on where to add new context +- Include cross-references between related files + +## Task 5: Update CLAUDE.md + +Update CLAUDE.md to reference the new chunked structure: +- Note that context is now organized in context-data/ directory +- Reference the index file (context-data/README.md) +- Provide guidance on which context files are most relevant for specific tasks +- Update any existing references to CONTEXT.md + +## Task 6: Archive Original CONTEXT.md + +- Rename CONTEXT.md to CONTEXT.md.backup +- Add a note in the backup explaining it has been chunked +- Keep the backup for reference + +## Best Practices for Chunking + +**Good chunk topics:** +- Project vision and goals +- User requirements and stories +- Technical specifications +- Architecture decisions +- Development workflow +- Domain knowledge +- Historical context and decisions +- Integration requirements + +**Chunking guidelines:** +- Each file should cover a cohesive topic +- Aim for 200-500 lines per file (adjust based on content) +- Use descriptive, consistent naming (kebab-case recommended) +- Avoid over-chunking (don't create files with only a few lines) +- Ensure chunks can be understood somewhat independently diff --git a/commands/claude-to-context.md b/commands/claude-to-context.md new file mode 100644 index 0000000..8892484 --- /dev/null +++ b/commands/claude-to-context.md @@ -0,0 +1,33 @@ +--- +description: Extract information from CLAUDE.md and incorporate into CONTEXT.md +--- + +This repository contains CLAUDE.md which provides structured instructions and context for Claude Code. + +I would like to extract valuable information from CLAUDE.md and incorporate it into CONTEXT.md as supplementary contextual information. This is useful when CLAUDE.md contains details that should be preserved in the more detailed, narrative context file. + +Execute these tasks in sequence: + +## Task 1: Extract Relevant Information + +Review CLAUDE.md and identify information that would be valuable to preserve in CONTEXT.md: +- Project requirements and specifications +- Implementation details and decisions +- Technical constraints or considerations +- Vision statements or project goals +- Background information about the project's purpose +- Any context that helps understand the "why" behind decisions + +Focus on information that provides deeper understanding rather than purely procedural instructions. + +## Task 2: Update CONTEXT.md + +Add the extracted information to CONTEXT.md, integrating it naturally with existing content: + +1. **Maintain the narrative style**: CONTEXT.md should remain conversational and human-friendly +2. **Organize logically**: Add clear section headers if introducing new topics +3. **Avoid duplication**: If similar information exists, merge thoughtfully rather than duplicate +4. **Preserve detail**: Don't summarize or condense - CONTEXT.md is meant to be comprehensive +5. **Add attribution**: Consider noting "Extracted from CLAUDE.md:" where appropriate + +The goal is to enrich CONTEXT.md with valuable information from CLAUDE.md while maintaining its character as a human-friendly, detailed context repository. diff --git a/commands/context-to-claude.md b/commands/context-to-claude.md new file mode 100644 index 0000000..0c83ee3 --- /dev/null +++ b/commands/context-to-claude.md @@ -0,0 +1,47 @@ +--- +description: Convert CONTEXT.md (human scratchpad) to CLAUDE.md (agent briefing) +--- + +This repository contains a file called CONTEXT.md (or context.md) which provides detailed, human-friendly description of the project purpose, motivations, and vision. + +This file likely contains conversational language, possibly captured using voice transcription, and may include typos, speech artifacts, and verbose explanations. + +Execute these tasks in sequence: + +## Task 1: Proofread CONTEXT.md + +Lightly edit CONTEXT.md to improve readability while preserving the human voice and intent: +- Add paragraph spacing for better readability +- Add punctuation where needed +- Fix typos and grammatical errors +- Fix errors that appear to be AI transcription mistakes +- Remove obvious speech artifacts (um, uh, repeated words) +- Preserve the conversational, expressive tone + +Do NOT over-edit or strip away personality. The goal is clarity, not sterility. + +## Task 2: Create/Update CLAUDE.md + +CLAUDE.md is the agent-facing context file that Claude Code automatically reads. Think of CONTEXT.md as the user's expressive scratchpad and CLAUDE.md as your structured implementation guide. + +Create or update CLAUDE.md with: + +1. **Project Overview**: Concise summary of purpose and goals +2. **Key Requirements**: Specific, actionable requirements extracted from CONTEXT.md +3. **Implementation Guidance**: Technical direction, architecture decisions, constraints +4. **Workflow Instructions**: How the agent should approach tasks in this project +5. **Context Reference Note**: Add this section: + +```markdown +## Human Context Reference + +This project includes a CONTEXT.md file containing detailed, human-authored context including: +- Project vision and motivations +- Detailed requirements and use cases +- User's thought process and decision rationale +- Additional background information + +When you need deeper understanding of the project's purpose or user intent, refer to CONTEXT.md for the full narrative context. +``` + +Keep CLAUDE.md focused, structured, and actionable. Extract the essence of what's in CONTEXT.md and present it in a format optimized for agent processing. diff --git a/commands/manual-context-update.md b/commands/manual-context-update.md new file mode 100644 index 0000000..2fb6abb --- /dev/null +++ b/commands/manual-context-update.md @@ -0,0 +1,59 @@ +--- +description: Manually edit and synchronize CONTEXT.md and CLAUDE.md +--- + +I would like to make manual updates to the context files in this repository. + +This command provides a guided workflow for making coordinated changes to both CONTEXT.md (human context) and CLAUDE.md (agent briefing). + +Execute these tasks interactively: + +## Task 1: Determine Update Type + +Ask the user which type of update they want to make: + +1. **Update CONTEXT.md only** - Add/edit human-friendly context without changing agent briefing +2. **Update CLAUDE.md only** - Refine agent instructions without changing source context +3. **Update both files** - Make coordinated changes to both files +4. **Restructure context** - Reorganize how context is stored (single file vs. chunked) + +## Task 2: Execute Updates Based on Type + +### For CONTEXT.md updates: +- Make the requested changes while preserving narrative style +- Ensure proper formatting and organization +- Maintain conversational tone + +### For CLAUDE.md updates: +- Make the requested changes while keeping it structured and actionable +- Ensure clarity and precision +- Maintain agent-optimized format + +### For coordinated updates: +- Update CONTEXT.md first with detailed information +- Then update CLAUDE.md to reflect new/changed requirements +- Ensure consistency between files + +### For restructuring: +- If converting to chunked context: create context-data/ directory, split content logically +- If consolidating: merge context-data/ files back into single CONTEXT.md +- Update CLAUDE.md to reference new structure + +## Task 3: Validate Consistency + +After making changes: +1. Verify CLAUDE.md accurately reflects current CONTEXT.md +2. Check that no conflicting information exists between files +3. Ensure all cross-references remain valid +4. Confirm proper formatting and organization + +## Task 4: Summarize Changes + +Provide a summary of: +- What was changed in each file +- Why the changes were made +- Any impacts on project structure or workflow + +## User Input Required + +Please describe what updates you'd like to make to the context files. diff --git a/commands/remove-from-context.md b/commands/remove-from-context.md new file mode 100644 index 0000000..3b5f9b6 --- /dev/null +++ b/commands/remove-from-context.md @@ -0,0 +1,51 @@ +--- +description: Remove outdated or incorrect information from the context pool +--- + +I would like to remove information from this repository's context pool. + +The context data is stored in CONTEXT.md (or in a context-data/ directory if chunked). + +I will specify what information should be removed. + +After I provide this specification, execute these tasks in order: + +## Task 1: Remove from Context Pool + +Locate and remove the specified information: + +**If using CONTEXT.md:** +- Find the section(s) containing the information to remove +- Delete the specified content +- Ensure remaining content flows naturally +- Adjust section headers if needed +- Preserve document structure and readability + +**If using context-data/ directory:** +- Identify file(s) containing the information to remove +- Remove the specified content from relevant files +- Delete entire files if they become empty or irrelevant +- Ensure cross-references in other files remain valid + +## Task 2: Update CLAUDE.md + +Review and update CLAUDE.md to ensure it remains accurate after the removal: + +1. **Remove obsolete information**: Delete any references to the removed context +2. **Update requirements**: Adjust project requirements if they were affected +3. **Revise guidance**: Update implementation guidance to reflect current context +4. **Check consistency**: Ensure CLAUDE.md is consistent with the updated context pool + +## Task 3: Confirm Changes + +Provide a summary of: +- What was removed from the context pool +- What changes were made to CLAUDE.md +- Whether any files were deleted (if using context-data/ directory) + +## User Input Required + +Please specify what information you'd like to remove from the context pool. You can: +- Describe the topic/content to remove +- Specify section names or file names +- Provide the actual text to remove diff --git a/hooks/hooks.json b/hooks/hooks.json new file mode 100644 index 0000000..7465634 --- /dev/null +++ b/hooks/hooks.json @@ -0,0 +1,23 @@ +{ + "hooks": [ + { + "name": "context-file-detector", + "description": "Detect CONTEXT.md files and remind agent to read them", + "type": "on_repo_open", + "enabled": true, + "priority": 10, + "script": "bash", + "command": "if [ -f 'CONTEXT.md' ] || [ -f 'context.md' ]; then echo 'CONTEXT.md detected in this repository. This file contains detailed human-authored context about the project. Consider reading it for deeper understanding of the project vision and requirements.'; fi; if [ -d 'context-data' ]; then echo 'context-data/ directory detected. This repository uses chunked context files. Review context-data/README.md for the organization structure.'; fi" + }, + { + "name": "context-sync-reminder", + "description": "Remind to sync CONTEXT.md and CLAUDE.md after significant changes", + "type": "on_file_write", + "enabled": true, + "priority": 5, + "filePatterns": ["CONTEXT.md", "context.md", "CLAUDE.md", "context-data/**/*.md"], + "script": "bash", + "command": "echo 'Context file modified. Remember to keep CONTEXT.md (human context) and CLAUDE.md (agent briefing) synchronized. Use /context-to-claude or /claude-to-context if needed.'" + } + ] +} diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..bcabf84 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,77 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:danielrosehill/Claude-Code-Context-Toolkit:.", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "01bee2511b3a7794d9bf9fd3a88a0ecf780cf2b1", + "treeHash": "60aa898f35d2338fe11534de9cefd914f3984fe47084e2c7e855c3c01beeddbd", + "generatedAt": "2025-11-28T10:16:00.873964Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "context-toolkit", + "description": "Implements the CONTEXT.md workflow system for managing human-authored context and agent-ready briefings in Claude Code", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "19a66f3d8cc98d89aef7a67fe269ca9203a5c6045f7dc13b5d0c392913e62f91" + }, + { + "path": "agents/context-manager.json", + "sha256": "1c9cccc82da29b18d9bdae3ce368b93bfc50b17a44c486d6cf47aa35317644ba" + }, + { + "path": "agents/context-converter.json", + "sha256": "5da4c21b3679b6950e209991aa0cf3093d119d947fd99728408b752d5b84d637" + }, + { + "path": "hooks/hooks.json", + "sha256": "6e82f27e4d9d8ea785642593996f6f1fe6d4b19f974a8c79bd7ba64388a6baff" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "d9c53bbbd37a91a719dc81e95e9c2b077a2c70c7702adc2939158078b310b150" + }, + { + "path": "commands/context-to-claude.md", + "sha256": "fa242bc548e00f1c84d763132b0530f48ef4f95c2626b601dfc91abc04542cad" + }, + { + "path": "commands/add-to-context.md", + "sha256": "9a292d19d67b17fa5256419a1c8cbdf6bcc781d4726a921bd1518d7f2745e430" + }, + { + "path": "commands/manual-context-update.md", + "sha256": "e0f707bff6f5dc14df6a3ce9446af30ae5667914cefd75fc58f9ec73c0ada9a5" + }, + { + "path": "commands/chunk-repo-context.md", + "sha256": "153b919f125ed72e4cc58bd6655d9eaa1130e570274bbf091763684021ceaa1f" + }, + { + "path": "commands/remove-from-context.md", + "sha256": "ca3bdbf7a31b6bc74c6b5e93e6a38d3b4a1fbd4595216545fb6260d69bba362d" + }, + { + "path": "commands/claude-to-context.md", + "sha256": "1c71ce9d7cb7d4182fd23003c6596ca16804c88ab796656e813136d8be46b64b" + } + ], + "dirSha256": "60aa898f35d2338fe11534de9cefd914f3984fe47084e2c7e855c3c01beeddbd" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file