feat: Pragmatic context management with plan keys and helper scripts

[brian-lai]

Summary

Successfully pivoted from speculative "smart context loading" documentation to building practical, testable bash scripts for context management. This PR delivers a complete helper script suite that enables multi-repo work and plan key-based context loading.

Key Achievement: Mid-execution pivot - recognized we were documenting features that don't exist, and redirected to building tools that work today.

Changes

🛠️ Helper Scripts Created (4 new scripts)

All scripts are executable, bash 3.2 compatible, and support multi-repo work:

1. para-list-files.sh - Extracts file paths from context.md for a given plan key
2. para-validate-files.sh - Validates which tracked files exist or are missing
3. para-resolve-paths.sh - Resolves repo-name/path format to absolute paths
4. para-generate-prompt.sh - Generates copy-pasteable prompts for Claude Code

📚 Documentation Updates

1. resources/CLAUDE.md

   • Removed 156 lines of speculative MCP content
   • Added 28-line Helper Scripts section
   • Rewrote Quickstart with real working examples
   • Focuses on what works today

2. commands/focus.md

   • Complete rewrite (252 → 263 lines)
   • From: Speculative auto-injection features
   • To: Practical manual workflow with helper scripts

3. examples/example-workflow.md

   • Updated to show plan key usage (AUTH-001)
   • Added helper script workflow example
   • Removed speculative MCP references

4. README.md

   • Updated examples to show plan key parameter
   • Changed terminology to reflect actual tools

Technical Details

Multi-Repo Support

Scripts automatically find git repositories by scanning:

• Current directory (if it's a git repo)
• Subdirectories with .git folders
• Parent directory's subdirectories

Example:

{
  "active_context": {
    "AUTH-001": {
      "repos": ["api-gateway", "user-service"],
      "files": [
        "api-gateway/src/middleware/auth.ts",
        "user-service/src/models/user.ts"
      ]
    }
  }
}

Plan Key System

Supports multiple concurrent work streams:

• Each plan gets a unique key (e.g., AUTH-001, FEAT-123)
• Files tracked per plan key
• Easy context switching between plans

Usage Example

# Generate prompt to load context
./context/servers/para-generate-prompt.sh AUTH-001

# Output:
# Please read the following files for AUTH-001:
# - /Users/you/project/src/models/User.ts
# - /Users/you/project/src/middleware/auth.ts
# ...

Testing

All scripts tested and validated:

• ✅ Unit testing (each script works independently)
• ✅ Integration testing (end-to-end workflow)
• ✅ Multi-repo scanning (found 11 repos correctly)
• ✅ Bash 3.2 compatibility (macOS default)
• ✅ Error handling (missing files, invalid keys, etc.)

Commits

• feat: Add para-resolve-paths and para-generate-prompt helper scripts
• docs: Rewrite focus command and CLAUDE.md to reflect pragmatic approach
• docs: Update examples to demonstrate plan keys and helper scripts
• chore: Mark CONTEXT-001 execution as complete
• docs: Add execution summary for CONTEXT-001

Previous commits:

• feat: Add para-validate-files.sh and para-list-files.sh
• docs: Phase 1 cuts - Remove speculative MCP sections
• refactor: Pivot from speculative documentation to pragmatic helper scripts
• And 6 more foundational commits

Metrics

Metric	Value
Scripts Created	4
Lines of Code	~400 (bash)
Documentation Reduction	-156 lines (CLAUDE.md)
Documentation Rewrite	263 lines (focus.md)
Files Modified	10
Commits	14

What Users Get

1. Practical Tools - 4 working scripts they can run today
2. Multi-Repo Support - Track files across multiple repositories
3. Plan Key System - Support for multiple concurrent work streams
4. Cleaner Documentation - Removed speculation, added practical guidance

Review Notes

• All scripts are tested and working
• Documentation matches implementation
• No breaking changes to existing functionality
• Ready for user testing and feedback

Related

• Plan: context/plans/2026-01-07-CONTEXT-001-smart-context-loading.md
• Summary: context/summaries/2026-01-08-CONTEXT-001-pragmatic-context-management-summary.md

🤖 Generated with Claude Code