create-claude-context 1.0.0 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +169 -146
  3. package/bin/create-claude-context.js +75 -61
  4. package/lib/ai-orchestrator.js +423 -0
  5. package/lib/call-tracer.js +444 -0
  6. package/lib/detector.js +456 -373
  7. package/lib/environment-detector.js +239 -0
  8. package/lib/index.js +271 -170
  9. package/lib/installer.js +371 -362
  10. package/lib/placeholder.js +269 -208
  11. package/lib/prompts.js +287 -287
  12. package/lib/spinner.js +60 -60
  13. package/lib/static-analyzer.js +729 -0
  14. package/lib/template-populator.js +835 -0
  15. package/lib/validate.js +147 -147
  16. package/package.json +59 -59
  17. package/templates/CLAUDE.md.template +235 -235
  18. package/templates/base/README.md +257 -257
  19. package/templates/base/RPI_WORKFLOW_PLAN.md +320 -320
  20. package/templates/base/agents/api-developer.md +76 -76
  21. package/templates/base/agents/context-engineer.md +525 -525
  22. package/templates/base/agents/core-architect.md +76 -76
  23. package/templates/base/agents/database-ops.md +76 -76
  24. package/templates/base/agents/deployment-ops.md +76 -76
  25. package/templates/base/agents/integration-hub.md +76 -76
  26. package/templates/base/analytics/README.md +114 -114
  27. package/templates/base/automation/config.json +58 -0
  28. package/templates/base/automation/generators/code-mapper.js +308 -0
  29. package/templates/base/automation/generators/index-builder.js +321 -0
  30. package/templates/base/automation/hooks/post-commit.sh +83 -0
  31. package/templates/base/automation/hooks/pre-commit.sh +103 -0
  32. package/templates/base/ci-templates/README.md +108 -108
  33. package/templates/base/ci-templates/github-actions/context-check.yml +144 -144
  34. package/templates/base/ci-templates/github-actions/validate-docs.yml +105 -105
  35. package/templates/base/commands/analytics.md +238 -238
  36. package/templates/base/commands/auto-sync.md +172 -0
  37. package/templates/base/commands/collab.md +194 -194
  38. package/templates/base/commands/help.md +450 -450
  39. package/templates/base/commands/rpi-implement.md +115 -115
  40. package/templates/base/commands/rpi-plan.md +93 -93
  41. package/templates/base/commands/rpi-research.md +88 -88
  42. package/templates/base/commands/session-resume.md +144 -0
  43. package/templates/base/commands/session-save.md +112 -0
  44. package/templates/base/commands/validate-all.md +77 -77
  45. package/templates/base/commands/verify-docs-current.md +86 -86
  46. package/templates/base/config/base.json +57 -57
  47. package/templates/base/config/environments/development.json +13 -13
  48. package/templates/base/config/environments/production.json +17 -17
  49. package/templates/base/config/environments/staging.json +13 -13
  50. package/templates/base/config/local.json.example +21 -21
  51. package/templates/base/context/.meta/generated-at.json +18 -0
  52. package/templates/base/context/ARCHITECTURE_SNAPSHOT.md +156 -156
  53. package/templates/base/context/CODE_TO_WORKFLOW_MAP.md +94 -94
  54. package/templates/base/context/FILE_OWNERSHIP.md +57 -0
  55. package/templates/base/context/INTEGRATION_POINTS.md +92 -0
  56. package/templates/base/context/KNOWN_GOTCHAS.md +195 -195
  57. package/templates/base/context/TESTING_MAP.md +95 -0
  58. package/templates/base/context/WORKFLOW_INDEX.md +129 -129
  59. package/templates/base/context/workflows/WORKFLOW_TEMPLATE.md +294 -294
  60. package/templates/base/indexes/agents/CAPABILITY_MATRIX.md +255 -255
  61. package/templates/base/indexes/agents/CATEGORY_INDEX.md +44 -44
  62. package/templates/base/indexes/code/CATEGORY_INDEX.md +38 -38
  63. package/templates/base/indexes/routing/CATEGORY_INDEX.md +39 -39
  64. package/templates/base/indexes/search/CATEGORY_INDEX.md +39 -39
  65. package/templates/base/indexes/workflows/CATEGORY_INDEX.md +38 -38
  66. package/templates/base/knowledge/README.md +98 -98
  67. package/templates/base/knowledge/sessions/README.md +88 -88
  68. package/templates/base/knowledge/sessions/TEMPLATE.md +150 -150
  69. package/templates/base/knowledge/shared/decisions/0001-adopt-context-engineering.md +144 -144
  70. package/templates/base/knowledge/shared/decisions/README.md +49 -49
  71. package/templates/base/knowledge/shared/decisions/TEMPLATE.md +123 -123
  72. package/templates/base/knowledge/shared/patterns/README.md +62 -62
  73. package/templates/base/knowledge/shared/patterns/TEMPLATE.md +120 -120
  74. package/templates/base/plans/PLAN_TEMPLATE.md +250 -250
  75. package/templates/base/research/RESEARCH_TEMPLATE.md +153 -153
  76. package/templates/base/schemas/agent.schema.json +141 -141
  77. package/templates/base/schemas/anchors.schema.json +54 -0
  78. package/templates/base/schemas/automation.schema.json +93 -0
  79. package/templates/base/schemas/command.schema.json +134 -134
  80. package/templates/base/schemas/hashes.schema.json +40 -0
  81. package/templates/base/schemas/manifest.schema.json +117 -117
  82. package/templates/base/schemas/plan.schema.json +136 -136
  83. package/templates/base/schemas/research.schema.json +115 -115
  84. package/templates/base/schemas/roles.schema.json +34 -0
  85. package/templates/base/schemas/session.schema.json +77 -0
  86. package/templates/base/schemas/settings.schema.json +244 -244
  87. package/templates/base/schemas/staleness.schema.json +53 -0
  88. package/templates/base/schemas/team-config.schema.json +42 -0
  89. package/templates/base/schemas/workflow.schema.json +126 -126
  90. package/templates/base/session/checkpoints/.gitkeep +2 -0
  91. package/templates/base/session/current/state.json +20 -0
  92. package/templates/base/session/history/.gitkeep +2 -0
  93. package/templates/base/settings.json +3 -57
  94. package/templates/base/standards/COMPATIBILITY.md +219 -219
  95. package/templates/base/standards/EXTENSION_GUIDELINES.md +280 -280
  96. package/templates/base/standards/QUALITY_CHECKLIST.md +211 -211
  97. package/templates/base/standards/README.md +66 -66
  98. package/templates/base/sync/anchors.json +6 -0
  99. package/templates/base/sync/hashes.json +6 -0
  100. package/templates/base/sync/staleness.json +10 -0
  101. package/templates/base/team/README.md +168 -168
  102. package/templates/base/team/config.json +79 -79
  103. package/templates/base/team/roles.json +145 -145
  104. package/templates/base/tools/bin/claude-context.js +151 -151
  105. package/templates/base/tools/lib/anchor-resolver.js +276 -0
  106. package/templates/base/tools/lib/config-loader.js +363 -363
  107. package/templates/base/tools/lib/detector.js +350 -350
  108. package/templates/base/tools/lib/diagnose.js +206 -206
  109. package/templates/base/tools/lib/drift-detector.js +373 -0
  110. package/templates/base/tools/lib/errors.js +199 -199
  111. package/templates/base/tools/lib/index.js +36 -24
  112. package/templates/base/tools/lib/init.js +192 -192
  113. package/templates/base/tools/lib/logger.js +230 -230
  114. package/templates/base/tools/lib/placeholder.js +201 -201
  115. package/templates/base/tools/lib/session-manager.js +354 -0
  116. package/templates/base/tools/lib/validate.js +521 -521
  117. package/templates/base/tools/package.json +49 -49
@@ -1,39 +1,39 @@
1
- # Routing Category Index
2
-
3
- ## Purpose
4
- Entry point for task routing and classification
5
-
6
- ## Task Types Available
7
-
8
- | Task Type | Description | When to Use |
9
- |-----------|-------------|-------------|
10
- | **Feature** | New feature implementation | When building new functionality |
11
- | **Bug Fix** | Issue resolution | When fixing bugs or issues |
12
- | **Refactor** | Code improvement | When refactoring existing code |
13
- | **Documentation** | Doc updates | When updating documentation |
14
- | **Technical Debt** | Legacy improvements | When addressing technical debt |
15
- | **Performance** | Optimization | When improving performance |
16
-
17
- ## Quick Start
18
-
19
- 1. Load this category index first (~5k tokens)
20
- 2. Identify relevant task type
21
- 3. Load routing matrix for detailed classification
22
- 4. Follow routing instructions for implementation
23
-
24
- ## Context Budget
25
- - Category Index: ~5k tokens (2.5% of context window)
26
- - Routing Matrix: ~10k tokens (5% of context window)
27
- - Implementation Guidance: ~30k tokens (15% of context window)
28
-
29
- ## Getting Started
30
-
31
- ```bash
32
- # Load category index first
33
- Read: .claude/indexes/routing/CATEGORY_INDEX.md
34
-
35
- # Then load relevant routing matrix
36
- Read: .claude/indexes/routing/[task_type].md
37
-
38
- # Finally follow routing instructions
39
- Follow guidance in routing matrix
1
+ # Routing Category Index
2
+
3
+ ## Purpose
4
+ Entry point for task routing and classification
5
+
6
+ ## Task Types Available
7
+
8
+ | Task Type | Description | When to Use |
9
+ |-----------|-------------|-------------|
10
+ | **Feature** | New feature implementation | When building new functionality |
11
+ | **Bug Fix** | Issue resolution | When fixing bugs or issues |
12
+ | **Refactor** | Code improvement | When refactoring existing code |
13
+ | **Documentation** | Doc updates | When updating documentation |
14
+ | **Technical Debt** | Legacy improvements | When addressing technical debt |
15
+ | **Performance** | Optimization | When improving performance |
16
+
17
+ ## Quick Start
18
+
19
+ 1. Load this category index first (~5k tokens)
20
+ 2. Identify relevant task type
21
+ 3. Load routing matrix for detailed classification
22
+ 4. Follow routing instructions for implementation
23
+
24
+ ## Context Budget
25
+ - Category Index: ~5k tokens (2.5% of context window)
26
+ - Routing Matrix: ~10k tokens (5% of context window)
27
+ - Implementation Guidance: ~30k tokens (15% of context window)
28
+
29
+ ## Getting Started
30
+
31
+ ```bash
32
+ # Load category index first
33
+ Read: .claude/indexes/routing/CATEGORY_INDEX.md
34
+
35
+ # Then load relevant routing matrix
36
+ Read: .claude/indexes/routing/[task_type].md
37
+
38
+ # Finally follow routing instructions
39
+ Follow guidance in routing matrix
@@ -1,39 +1,39 @@
1
- # Search Category Index
2
-
3
- ## Purpose
4
- Entry point for search strategies and pattern recognition
5
-
6
- ## Search Patterns Available
7
-
8
- | Pattern Type | Description | When to Use |
9
- |--------------|-------------|-------------|
10
- | **Configuration Values** | Environment variables, hardcoded settings | When searching for config values |
11
- | **Business Logic** | Core application logic files | When locating business rules |
12
- | **Database Schema** | Models, migrations, queries | When investigating data structures |
13
- | **External Integrations** | API calls, webhooks, Connectors | When examining third-party integrations |
14
- | **Error Handling** | Exception handling patterns | When debugging error scenarios |
15
- | **Performance Bottlenecks** | Heavy computations, slow queries | When optimizing performance |
16
-
17
- ## Quick Start
18
-
19
- 1. Load this category index first (~5k tokens)
20
- 2. Identify relevant search pattern
21
- 3. Load pattern details for specific implementation
22
- 4. Use search strategies for investigation
23
-
24
- ## Context Budget
25
- - Category Index: ~5k tokens (2.5% of context window)
26
- - Pattern Details: ~10k tokens (5% of context window)
27
- - Search Execution: ~30k tokens (15% of context window)
28
-
29
- ## Getting Started
30
-
31
- ```bash
32
- # Load category index first
33
- Read: .claude/indexes/search/CATEGORY_INDEX.md
34
-
35
- # Then load relevant pattern details
36
- Read: .claude/indexes/search/[pattern_type].md
37
-
38
- # Finally execute search strategy
39
- Follow pattern instructions for investigation
1
+ # Search Category Index
2
+
3
+ ## Purpose
4
+ Entry point for search strategies and pattern recognition
5
+
6
+ ## Search Patterns Available
7
+
8
+ | Pattern Type | Description | When to Use |
9
+ |--------------|-------------|-------------|
10
+ | **Configuration Values** | Environment variables, hardcoded settings | When searching for config values |
11
+ | **Business Logic** | Core application logic files | When locating business rules |
12
+ | **Database Schema** | Models, migrations, queries | When investigating data structures |
13
+ | **External Integrations** | API calls, webhooks, Connectors | When examining third-party integrations |
14
+ | **Error Handling** | Exception handling patterns | When debugging error scenarios |
15
+ | **Performance Bottlenecks** | Heavy computations, slow queries | When optimizing performance |
16
+
17
+ ## Quick Start
18
+
19
+ 1. Load this category index first (~5k tokens)
20
+ 2. Identify relevant search pattern
21
+ 3. Load pattern details for specific implementation
22
+ 4. Use search strategies for investigation
23
+
24
+ ## Context Budget
25
+ - Category Index: ~5k tokens (2.5% of context window)
26
+ - Pattern Details: ~10k tokens (5% of context window)
27
+ - Search Execution: ~30k tokens (15% of context window)
28
+
29
+ ## Getting Started
30
+
31
+ ```bash
32
+ # Load category index first
33
+ Read: .claude/indexes/search/CATEGORY_INDEX.md
34
+
35
+ # Then load relevant pattern details
36
+ Read: .claude/indexes/search/[pattern_type].md
37
+
38
+ # Finally execute search strategy
39
+ Follow pattern instructions for investigation
@@ -1,38 +1,38 @@
1
- # Workflows Category Index
2
-
3
- ## Purpose
4
- Entry point for workflow-related navigation and task classification
5
-
6
- ## Categories Available
7
-
8
- | Category | Description | When to Use |
9
- |----------|-------------|-------------|
10
- | **jobs** | Job-related workflows (hiring, onboarding, payroll) | When working with HR or recruitment processes |
11
- | **payment** | Payment processing workflows | When implementing payment features |
12
- | **email** | Email-related workflows | When building email functionality |
13
- | **reporting** | Reporting and analytics workflows | When creating dashboards or reports |
14
- | **authentication** | Auth-related workflows | When implementing login/registration features |
15
-
16
- ## Quick Start
17
-
18
- 1. Load this category index first (~5k tokens)
19
- 2. Identify relevant category
20
- 3. Load domain index for detailed navigation
21
- 4. Access workflow detail files for implementation
22
-
23
- ## Context Budget
24
- - Category Index: ~5k tokens (2.5% of context window)
25
- - Domain Index: ~15k tokens (7.5% of context window)
26
- - Workflow Detail: ~40k tokens (20% of context window)
27
-
28
- ## Getting Started
29
-
30
- ```bash
31
- # Load category index first
32
- Read: .claude/indexes/workflows/CATEGORY_INDEX.md
33
-
34
- # Then load relevant domain index
35
- Read: .claude/indexes/workflows/[category].md
36
-
37
- # Finally load workflow detail file
38
- Read: .claude/context/workflows/[workflow].md
1
+ # Workflows Category Index
2
+
3
+ ## Purpose
4
+ Entry point for workflow-related navigation and task classification
5
+
6
+ ## Categories Available
7
+
8
+ | Category | Description | When to Use |
9
+ |----------|-------------|-------------|
10
+ | **jobs** | Job-related workflows (hiring, onboarding, payroll) | When working with HR or recruitment processes |
11
+ | **payment** | Payment processing workflows | When implementing payment features |
12
+ | **email** | Email-related workflows | When building email functionality |
13
+ | **reporting** | Reporting and analytics workflows | When creating dashboards or reports |
14
+ | **authentication** | Auth-related workflows | When implementing login/registration features |
15
+
16
+ ## Quick Start
17
+
18
+ 1. Load this category index first (~5k tokens)
19
+ 2. Identify relevant category
20
+ 3. Load domain index for detailed navigation
21
+ 4. Access workflow detail files for implementation
22
+
23
+ ## Context Budget
24
+ - Category Index: ~5k tokens (2.5% of context window)
25
+ - Domain Index: ~15k tokens (7.5% of context window)
26
+ - Workflow Detail: ~40k tokens (20% of context window)
27
+
28
+ ## Getting Started
29
+
30
+ ```bash
31
+ # Load category index first
32
+ Read: .claude/indexes/workflows/CATEGORY_INDEX.md
33
+
34
+ # Then load relevant domain index
35
+ Read: .claude/indexes/workflows/[category].md
36
+
37
+ # Finally load workflow detail file
38
+ Read: .claude/context/workflows/[workflow].md
@@ -1,98 +1,98 @@
1
- # Shared Knowledge Base
2
-
3
- Central repository for team knowledge, decisions, patterns, and session handoffs.
4
-
5
- ## Directory Structure
6
-
7
- ```
8
- knowledge/
9
- ├── shared/ # Team-shared knowledge
10
- │ ├── decisions/ # Architecture Decision Records (ADRs)
11
- │ └── patterns/ # Reusable code patterns
12
- ├── sessions/ # Session handoff documents
13
- └── README.md # This file
14
- ```
15
-
16
- ## Shared Knowledge
17
-
18
- ### Architecture Decision Records (ADRs)
19
-
20
- Located in `shared/decisions/`, ADRs document significant architectural decisions.
21
-
22
- **Creating an ADR:**
23
- 1. Copy `shared/decisions/TEMPLATE.md`
24
- 2. Name it `NNNN-descriptive-title.md` (e.g., `0001-use-postgresql.md`)
25
- 3. Fill in all sections
26
- 4. Submit for team review
27
-
28
- **ADR Statuses:**
29
- - `proposed` - Under discussion
30
- - `accepted` - Approved and in effect
31
- - `deprecated` - Superseded by another ADR
32
- - `rejected` - Not approved
33
-
34
- ### Reusable Patterns
35
-
36
- Located in `shared/patterns/`, patterns document proven solutions to common problems.
37
-
38
- **Pattern Categories:**
39
- - `api/` - API design patterns
40
- - `data/` - Data handling patterns
41
- - `ui/` - User interface patterns
42
- - `testing/` - Testing patterns
43
- - `security/` - Security patterns
44
-
45
- ## Session Handoffs
46
-
47
- Located in `sessions/`, handoff documents enable continuity between Claude Code sessions.
48
-
49
- **Handoff Document Contents:**
50
- - Session summary
51
- - Work completed
52
- - Work in progress
53
- - Blockers and issues
54
- - Next steps
55
- - Relevant context
56
-
57
- **Creating a Handoff:**
58
- ```
59
- /collab handoff
60
- ```
61
-
62
- **Naming Convention:**
63
- `YYYY-MM-DD-HH-MM-member-id.md`
64
-
65
- ## Usage
66
-
67
- ### Adding Knowledge
68
-
69
- 1. Create document in appropriate directory
70
- 2. Follow the template structure
71
- 3. Run `/collab sync` to notify team
72
-
73
- ### Finding Knowledge
74
-
75
- 1. Check category directories for relevant content
76
- 2. Use grep/search for specific terms
77
- 3. Review recent session handoffs for context
78
-
79
- ### Updating Knowledge
80
-
81
- 1. Edit the document
82
- 2. Update the `last_updated` metadata
83
- 3. Add to revision history if significant
84
-
85
- ## Retention Policy
86
-
87
- | Content Type | Retention |
88
- |--------------|-----------|
89
- | ADRs | Permanent (archive deprecated) |
90
- | Patterns | Permanent (version updates) |
91
- | Session Handoffs | 90 days (archive important ones) |
92
-
93
- ## Best Practices
94
-
95
- 1. **Keep it Current** - Update knowledge when code changes
96
- 2. **Be Specific** - Include concrete examples
97
- 3. **Link to Code** - Reference file:line where applicable
98
- 4. **Review Regularly** - Prune outdated content monthly
1
+ # Shared Knowledge Base
2
+
3
+ Central repository for team knowledge, decisions, patterns, and session handoffs.
4
+
5
+ ## Directory Structure
6
+
7
+ ```
8
+ knowledge/
9
+ ├── shared/ # Team-shared knowledge
10
+ │ ├── decisions/ # Architecture Decision Records (ADRs)
11
+ │ └── patterns/ # Reusable code patterns
12
+ ├── sessions/ # Session handoff documents
13
+ └── README.md # This file
14
+ ```
15
+
16
+ ## Shared Knowledge
17
+
18
+ ### Architecture Decision Records (ADRs)
19
+
20
+ Located in `shared/decisions/`, ADRs document significant architectural decisions.
21
+
22
+ **Creating an ADR:**
23
+ 1. Copy `shared/decisions/TEMPLATE.md`
24
+ 2. Name it `NNNN-descriptive-title.md` (e.g., `0001-use-postgresql.md`)
25
+ 3. Fill in all sections
26
+ 4. Submit for team review
27
+
28
+ **ADR Statuses:**
29
+ - `proposed` - Under discussion
30
+ - `accepted` - Approved and in effect
31
+ - `deprecated` - Superseded by another ADR
32
+ - `rejected` - Not approved
33
+
34
+ ### Reusable Patterns
35
+
36
+ Located in `shared/patterns/`, patterns document proven solutions to common problems.
37
+
38
+ **Pattern Categories:**
39
+ - `api/` - API design patterns
40
+ - `data/` - Data handling patterns
41
+ - `ui/` - User interface patterns
42
+ - `testing/` - Testing patterns
43
+ - `security/` - Security patterns
44
+
45
+ ## Session Handoffs
46
+
47
+ Located in `sessions/`, handoff documents enable continuity between Claude Code sessions.
48
+
49
+ **Handoff Document Contents:**
50
+ - Session summary
51
+ - Work completed
52
+ - Work in progress
53
+ - Blockers and issues
54
+ - Next steps
55
+ - Relevant context
56
+
57
+ **Creating a Handoff:**
58
+ ```
59
+ /collab handoff
60
+ ```
61
+
62
+ **Naming Convention:**
63
+ `YYYY-MM-DD-HH-MM-member-id.md`
64
+
65
+ ## Usage
66
+
67
+ ### Adding Knowledge
68
+
69
+ 1. Create document in appropriate directory
70
+ 2. Follow the template structure
71
+ 3. Run `/collab sync` to notify team
72
+
73
+ ### Finding Knowledge
74
+
75
+ 1. Check category directories for relevant content
76
+ 2. Use grep/search for specific terms
77
+ 3. Review recent session handoffs for context
78
+
79
+ ### Updating Knowledge
80
+
81
+ 1. Edit the document
82
+ 2. Update the `last_updated` metadata
83
+ 3. Add to revision history if significant
84
+
85
+ ## Retention Policy
86
+
87
+ | Content Type | Retention |
88
+ |--------------|-----------|
89
+ | ADRs | Permanent (archive deprecated) |
90
+ | Patterns | Permanent (version updates) |
91
+ | Session Handoffs | 90 days (archive important ones) |
92
+
93
+ ## Best Practices
94
+
95
+ 1. **Keep it Current** - Update knowledge when code changes
96
+ 2. **Be Specific** - Include concrete examples
97
+ 3. **Link to Code** - Reference file:line where applicable
98
+ 4. **Review Regularly** - Prune outdated content monthly
@@ -1,88 +1,88 @@
1
- # Session Handoffs
2
-
3
- This directory contains session handoff documents that enable continuity between Claude Code sessions.
4
-
5
- ## Purpose
6
-
7
- Session handoffs capture:
8
- - Work completed during a session
9
- - Work in progress with current state
10
- - Blockers and issues encountered
11
- - Context needed for continuation
12
- - Recommended next steps
13
-
14
- ## Creating a Handoff
15
-
16
- Use the `/collab handoff` command at the end of a session:
17
-
18
- ```
19
- /collab handoff
20
- ```
21
-
22
- This generates a handoff document from the current session state.
23
-
24
- ## Manual Handoff
25
-
26
- If the command isn't available, copy `TEMPLATE.md` and fill in:
27
-
28
- 1. Session metadata
29
- 2. Completed work summary
30
- 3. In-progress work state
31
- 4. Any blockers or issues
32
- 5. Context for next session
33
- 6. Recommended next steps
34
-
35
- ## Naming Convention
36
-
37
- Handoff files are named:
38
- ```
39
- YYYY-MM-DD-HH-MM-member-id.md
40
- ```
41
-
42
- Example: `2024-01-15-14-30-dev-1.md`
43
-
44
- ## Finding Relevant Handoffs
45
-
46
- ### Most Recent
47
-
48
- Sort by filename (most recent first):
49
- ```bash
50
- ls -r sessions/*.md
51
- ```
52
-
53
- ### By Team Member
54
-
55
- ```bash
56
- ls sessions/*-member-id.md
57
- ```
58
-
59
- ### By Date Range
60
-
61
- ```bash
62
- ls sessions/2024-01-*.md
63
- ```
64
-
65
- ## Retention
66
-
67
- | Age | Action |
68
- |-----|--------|
69
- | < 7 days | Keep (active reference) |
70
- | 7-30 days | Review for archival |
71
- | 30-90 days | Archive important, delete routine |
72
- | > 90 days | Delete unless historically significant |
73
-
74
- ## Archiving
75
-
76
- Important handoffs (major feature completions, incident resolutions) should be:
77
-
78
- 1. Moved to `sessions/archive/`
79
- 2. Renamed with descriptive suffix: `YYYY-MM-DD-feature-name.md`
80
- 3. Referenced in relevant ADRs if applicable
81
-
82
- ## Best Practices
83
-
84
- 1. **Create handoffs proactively** - Don't wait until context is lost
85
- 2. **Be specific** - Include file paths, line numbers, commit hashes
86
- 3. **Note blockers clearly** - Help the next person avoid wasted effort
87
- 4. **Include context** - Share discoveries that aren't in the code
88
- 5. **Suggest next steps** - Prioritize what should happen next
1
+ # Session Handoffs
2
+
3
+ This directory contains session handoff documents that enable continuity between Claude Code sessions.
4
+
5
+ ## Purpose
6
+
7
+ Session handoffs capture:
8
+ - Work completed during a session
9
+ - Work in progress with current state
10
+ - Blockers and issues encountered
11
+ - Context needed for continuation
12
+ - Recommended next steps
13
+
14
+ ## Creating a Handoff
15
+
16
+ Use the `/collab handoff` command at the end of a session:
17
+
18
+ ```
19
+ /collab handoff
20
+ ```
21
+
22
+ This generates a handoff document from the current session state.
23
+
24
+ ## Manual Handoff
25
+
26
+ If the command isn't available, copy `TEMPLATE.md` and fill in:
27
+
28
+ 1. Session metadata
29
+ 2. Completed work summary
30
+ 3. In-progress work state
31
+ 4. Any blockers or issues
32
+ 5. Context for next session
33
+ 6. Recommended next steps
34
+
35
+ ## Naming Convention
36
+
37
+ Handoff files are named:
38
+ ```
39
+ YYYY-MM-DD-HH-MM-member-id.md
40
+ ```
41
+
42
+ Example: `2024-01-15-14-30-dev-1.md`
43
+
44
+ ## Finding Relevant Handoffs
45
+
46
+ ### Most Recent
47
+
48
+ Sort by filename (most recent first):
49
+ ```bash
50
+ ls -r sessions/*.md
51
+ ```
52
+
53
+ ### By Team Member
54
+
55
+ ```bash
56
+ ls sessions/*-member-id.md
57
+ ```
58
+
59
+ ### By Date Range
60
+
61
+ ```bash
62
+ ls sessions/2024-01-*.md
63
+ ```
64
+
65
+ ## Retention
66
+
67
+ | Age | Action |
68
+ |-----|--------|
69
+ | < 7 days | Keep (active reference) |
70
+ | 7-30 days | Review for archival |
71
+ | 30-90 days | Archive important, delete routine |
72
+ | > 90 days | Delete unless historically significant |
73
+
74
+ ## Archiving
75
+
76
+ Important handoffs (major feature completions, incident resolutions) should be:
77
+
78
+ 1. Moved to `sessions/archive/`
79
+ 2. Renamed with descriptive suffix: `YYYY-MM-DD-feature-name.md`
80
+ 3. Referenced in relevant ADRs if applicable
81
+
82
+ ## Best Practices
83
+
84
+ 1. **Create handoffs proactively** - Don't wait until context is lost
85
+ 2. **Be specific** - Include file paths, line numbers, commit hashes
86
+ 3. **Note blockers clearly** - Help the next person avoid wasted effort
87
+ 4. **Include context** - Share discoveries that aren't in the code
88
+ 5. **Suggest next steps** - Prioritize what should happen next