docs(core): refine project intelligence system and deprecate legacy context (#93)
* feat(context): Add project intelligence system - Add project-intelligence.md standard (what & why) - Add project-intelligence-management.md guide (how to manage) - Add project-intelligence/ folder with 6 context files: - navigation.md (quick overview & routes) - business-domain.md (business context, users, value) - technical-domain.md (stack, architecture, decisions) - business-tech-bridge.md (business → technical mapping) - decisions-log.md (decision history with context) - living-notes.md (active issues, debt, questions) - Update standards navigation with new entries - Register all new contexts in registry.json This enables projects to document and maintain business + technical context for quick onboarding and lasting project understanding. * fix(registry): Add project-intelligence to profiles - Add context:project-intelligence/* to developer, business, full, and advanced profiles - Ensures project intelligence contexts are included when these profiles are selected This complements commit c731328 which added the context entries. * docs(core): refine project intelligence system and deprecate legacy context
This commit is contained in:
Darren Hinde
GitHub
parent
0439a7eb80
commit
7590a7a2ff
12 changed files with 1063 additions and 10 deletions
|
|
@ -12,6 +12,8 @@
|
|||
| `test-coverage.md` | Testing standards | ⭐⭐⭐⭐⭐ | Writing tests |
|
||||
| `documentation.md` | Documentation rules | ⭐⭐⭐⭐ | Writing docs |
|
||||
| `security-patterns.md` | Security best practices | ⭐⭐⭐⭐ | Security review, patterns |
|
||||
| `project-intelligence.md` | What and why | ⭐⭐⭐⭐ | Onboarding, understanding projects |
|
||||
| `project-intelligence-management.md` | How to manage | ⭐⭐⭐ | Managing intelligence files |
|
||||
| `code-analysis.md` | Analysis approaches | ⭐⭐⭐ | Analyzing code, debugging |
|
||||
|
||||
---
|
||||
|
|
@ -34,9 +36,14 @@
|
|||
2. Load `security-patterns.md` (high)
|
||||
3. Load `test-coverage.md` (high)
|
||||
|
||||
**For project onboarding/understanding**:
|
||||
1. Load `project-intelligence.md` (high)
|
||||
2. Then load: `../../project-intelligence/` folder for full project context
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- **Workflows** → `../workflows/navigation.md`
|
||||
- **Development Principles** → `../../development/principles/`
|
||||
- **Project Intelligence** → `../../project-intelligence/navigation.md` (full project context)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,249 @@
|
|||
<!-- Context: standards/intelligence-mgmt | Priority: high | Version: 1.0 | Updated: 2025-01-12 -->
|
||||
|
||||
# Project Intelligence Management
|
||||
|
||||
> **What**: How to manage project intelligence files and folders.
|
||||
> **When**: Use this guide when adding, updating, or removing intelligence files.
|
||||
> **Related**: See `project-intelligence.md` for what and why.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Action | Do This |
|
||||
|--------|---------|
|
||||
| Update existing file | Edit + bump frontmatter version |
|
||||
| Add new file | Create `.md` + add to navigation.md |
|
||||
| Add subfolder | Create folder + `navigation.md` + update parent nav |
|
||||
| Remove file | Rename `.deprecated.md` + archive, don't delete |
|
||||
|
||||
---
|
||||
|
||||
## Update Existing Files
|
||||
|
||||
**When**:
|
||||
- Business changes → Update `business-domain.md`
|
||||
- New decision → Add to `decisions-log.md`
|
||||
- New issues → Update `living-notes.md`
|
||||
- Feature launch → Update `business-tech-bridge.md`
|
||||
- Stack changes → Update `technical-domain.md`
|
||||
|
||||
**Process**:
|
||||
1. Edit the file
|
||||
2. Update frontmatter:
|
||||
```html
|
||||
<!-- Context: {category} | Priority: {level} | Version: {X.Y} | Updated: {YYYY-MM-DD} -->
|
||||
```
|
||||
3. Keep under 200 lines
|
||||
4. Commit with message like: `docs: Update business-domain.md with new market focus`
|
||||
|
||||
---
|
||||
|
||||
## Add New Files
|
||||
|
||||
**When**:
|
||||
- New domain area needs dedicated docs
|
||||
- Existing file exceeds 200 lines
|
||||
- Specialized context requires separation
|
||||
|
||||
**Naming**:
|
||||
- Kebab-case: `user-research.md`, `api-docs.md`
|
||||
- Descriptive: filename tells you what's inside
|
||||
|
||||
**Template**:
|
||||
```html
|
||||
<!-- Context: project-intelligence/{filename} | Priority: {high|medium} | Version: 1.0 | Updated: {YYYY-MM-DD} -->
|
||||
|
||||
# File Title
|
||||
|
||||
> One-line purpose statement
|
||||
|
||||
## Quick Reference
|
||||
|
||||
- **Purpose**: [What this covers]
|
||||
- **Update When**: [Triggers]
|
||||
- **Related Files**: [Links]
|
||||
|
||||
## Content
|
||||
|
||||
[Follow patterns from existing files]
|
||||
|
||||
## Related Files
|
||||
|
||||
- [File 1] - [Description]
|
||||
```
|
||||
|
||||
**Process**:
|
||||
1. Create file in `project-intelligence/`
|
||||
2. Add frontmatter with `project-intelligence/{filename}`
|
||||
3. Follow existing file patterns
|
||||
4. Keep under 200 lines
|
||||
5. Add to `navigation.md`
|
||||
|
||||
---
|
||||
|
||||
## Create Subfolders
|
||||
|
||||
**When**:
|
||||
- 5+ related files need grouping
|
||||
- Subdomain warrants separation (e.g., `api/`, `mobile/`, `integrations/`)
|
||||
- Improves navigation clarity
|
||||
|
||||
**Structure**:
|
||||
```
|
||||
project-intelligence/
|
||||
├── navigation.md # Root nav
|
||||
├── [new-subfolder]/ # Create this
|
||||
│ ├── navigation.md # Subfolder nav required
|
||||
│ ├── file-1.md
|
||||
│ └── file-2.md
|
||||
```
|
||||
|
||||
**Process**:
|
||||
1. Create folder: `mkdir project-intelligence/{name}/`
|
||||
2. Create `navigation.md` inside:
|
||||
```html
|
||||
<!-- Context: project-intelligence/{name}/nav | Priority: medium | Version: 1.0 | Updated: {YYYY-MM-DD} -->
|
||||
|
||||
# {Name} Navigation
|
||||
|
||||
> Quick overview
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `file-1.md` | [Desc] |
|
||||
```
|
||||
3. Add content files
|
||||
4. Update root `navigation.md` with subfolder entry
|
||||
|
||||
**Rule**: Every subfolder MUST have `navigation.md`. Avoid nesting deeper than 2 levels (e.g., `project-intelligence/domain/subdomain/`) to prevent context fragmentation.
|
||||
|
||||
---
|
||||
|
||||
## Remove/Deprecate Files
|
||||
|
||||
**When**:
|
||||
- Content moved elsewhere
|
||||
- File no longer relevant
|
||||
- Merged with another file
|
||||
|
||||
**Process**:
|
||||
1. Rename: `filename.md` → `filename.deprecated.md`
|
||||
2. Add frontmatter:
|
||||
```html
|
||||
<!-- DEPRECATED: {YYYY-MM-DD} - {Reason} -->
|
||||
<!-- REPLACED BY: {new-file.md} -->
|
||||
```
|
||||
3. Add banner at top:
|
||||
> ⚠️ **DEPRECATED**: See `new-file.md` for current info
|
||||
4. Mark as deprecated in `navigation.md`
|
||||
|
||||
**Never Delete**:
|
||||
- Decision history (archive instead)
|
||||
- Lessons learned (move to `living-notes.md`)
|
||||
- Context that might be needed later
|
||||
|
||||
---
|
||||
|
||||
## Version Tracking
|
||||
|
||||
**Frontmatter**:
|
||||
```html
|
||||
<!-- Context: {category} | Priority: {level} | Version: {MAJOR.MINOR} | Updated: {YYYY-MM-DD} -->
|
||||
```
|
||||
|
||||
**Version Rules**:
|
||||
| Change | Version |
|
||||
|--------|---------|
|
||||
| New file | 1.0 |
|
||||
| Content addition/update | MINOR |
|
||||
| Structure change | MAJOR |
|
||||
| Typo fix | PATCH |
|
||||
|
||||
**Date**: Always `YYYY-MM-DD`
|
||||
|
||||
---
|
||||
|
||||
## Quality Standards
|
||||
|
||||
**Line Limits**:
|
||||
- Files: <200 lines
|
||||
- Sections: 3-7 per file
|
||||
|
||||
**Required Elements**:
|
||||
- Frontmatter with all fields
|
||||
- Quick Reference section
|
||||
- Related files section
|
||||
|
||||
**Anti-Patterns**:
|
||||
❌ Mix concerns in one file
|
||||
❌ Exceed 200 lines
|
||||
❌ Delete files (archive instead)
|
||||
❌ Skip frontmatter
|
||||
❌ Duplicate information
|
||||
|
||||
✅ Keep focused and scannable
|
||||
✅ Archive deprecated content
|
||||
✅ Use frontmatter consistently
|
||||
✅ Link to related files
|
||||
|
||||
---
|
||||
|
||||
## Governance
|
||||
|
||||
**Ownership**:
|
||||
| Area | Owner | Responsibility |
|
||||
|------|-------|----------------|
|
||||
| Business domain | Product Owner | Keep current, accurate |
|
||||
| Technical domain | Tech Lead | Keep current, accurate |
|
||||
| Decisions log | Tech Lead | Document decisions |
|
||||
| Living notes | Team | Keep active items current |
|
||||
|
||||
**Review Cadence**:
|
||||
| Activity | Frequency |
|
||||
|----------|-----------|
|
||||
| Quick review | Per PR |
|
||||
| Full review | Quarterly |
|
||||
| Archive review | Semi-annually |
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
### Add New Intelligence File
|
||||
- [ ] Follow naming convention
|
||||
- [ ] Add complete frontmatter
|
||||
- [ ] Include Quick Reference
|
||||
- [ ] Keep under 200 lines
|
||||
- [ ] Add to navigation.md
|
||||
- [ ] Link from related files
|
||||
- [ ] Version: 1.0
|
||||
|
||||
### Update Existing File
|
||||
- [ ] Make targeted changes
|
||||
- [ ] Update version/date in frontmatter
|
||||
- [ ] Verify <200 lines
|
||||
- [ ] Update navigation if needed
|
||||
- [ ] Update related files
|
||||
|
||||
### Create Subfolder
|
||||
- [ ] Verify warranted (5+ files)
|
||||
- [ ] Create folder with kebab-case name
|
||||
- [ ] Create `navigation.md` inside
|
||||
- [ ] Add subfolder to parent navigation
|
||||
- [ ] Create content files
|
||||
|
||||
### Deprecate File
|
||||
- [ ] Rename with `.deprecated.md`
|
||||
- [ ] Add deprecation frontmatter
|
||||
- [ ] Add deprecation banner
|
||||
- [ ] Mark deprecated in navigation
|
||||
- [ ] Document replacement
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Standard**: `project-intelligence.md`
|
||||
- **Project Intelligence**: `../../project-intelligence/navigation.md`
|
||||
- **Context System**: `../context-system.md`
|
||||
77
.opencode/context/core/standards/project-intelligence.md
Normal file
77
.opencode/context/core/standards/project-intelligence.md
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
<!-- Context: standards/intelligence | Priority: high | Version: 1.0 | Updated: 2025-01-12 -->
|
||||
|
||||
# Project Intelligence
|
||||
|
||||
> **What**: Living documentation that bridges business domain and technical implementation.
|
||||
> **Why**: Quick project understanding and onboarding for developers, agents, and stakeholders.
|
||||
> **Where**: `.opencode/context/project-intelligence/` (dedicated folder)
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| What You Need | File | Description |
|
||||
|---------------|------|-------------|
|
||||
| Understand the "why" | `business-domain.md` | Problem, users, value |
|
||||
| Understand the "how" | `technical-domain.md` | Stack, architecture |
|
||||
| See the connection | `business-tech-bridge.md` | Business → technical mapping |
|
||||
| Know the context | `decisions-log.md` | Why decisions were made |
|
||||
| Current state | `living-notes.md` | Active issues, debt, questions |
|
||||
|
||||
## Why This Exists
|
||||
|
||||
Projects fail when:
|
||||
- Business intent is lost in code
|
||||
- Technical decisions aren't documented with context
|
||||
- New members spend weeks instead of hours understanding the project
|
||||
- Context lives only in people's heads (who leave)
|
||||
|
||||
This ensures **business and technical domains speak the same language**.
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
.opencode/context/
|
||||
├── project-intelligence/ # Project-specific context
|
||||
│ ├── navigation.md # Quick overview & routes
|
||||
│ ├── business-domain.md # Business context, problems solved
|
||||
│ ├── technical-domain.md # Stack, architecture, decisions
|
||||
│ ├── business-tech-bridge.md # How business needs → solutions
|
||||
│ ├── decisions-log.md # Decisions with rationale
|
||||
│ └── living-notes.md # Active issues, technical debt
|
||||
└── core/ # Universal standards
|
||||
```
|
||||
|
||||
## Onboarding Checklist
|
||||
|
||||
For new team members or agents:
|
||||
|
||||
- [ ] Read `navigation.md` (this file)
|
||||
- [ ] Read `business-domain.md` to understand the "why"
|
||||
- [ ] Read `technical-domain.md` to understand the "how"
|
||||
- [ ] Review `business-tech-bridge.md` to see the connection
|
||||
- [ ] Check `decisions-log.md` for context on key choices
|
||||
- [ ] Review `living-notes.md` for current state
|
||||
- [ ] Explore codebase with this context loaded
|
||||
|
||||
## How to Keep This Alive
|
||||
|
||||
| Trigger | Action |
|
||||
|---------|--------|
|
||||
| Business direction shifts | Update `business-domain.md` |
|
||||
| New technical decision | Add to `decisions-log.md` |
|
||||
| New issues or debt | Update `living-notes.md` |
|
||||
| Feature launch | Update `business-tech-bridge.md` |
|
||||
| Stack changes | Update `technical-domain.md` |
|
||||
|
||||
**Full Management Guide**: See `.opencode/context/core/standards/project-intelligence-management.md`
|
||||
|
||||
## Integration with Context System
|
||||
|
||||
- **Lazy Loading**: Load project intelligence first when joining a project
|
||||
- **Layering**: Then load standards and specific context as needed
|
||||
- **Reference**: See `.opencode/context/core/context-system.md` for system overview
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Management Guide**: `.opencode/context/core/standards/project-intelligence-management.md`
|
||||
- **Context System**: `.opencode/context/core/context-system.md`
|
||||
- **Standards Index**: `.opencode/context/core/standards/navigation.md`
|
||||
88
.opencode/context/project-intelligence/business-domain.md
Normal file
88
.opencode/context/project-intelligence/business-domain.md
Normal file
|
|
@ -0,0 +1,88 @@
|
|||
<!-- Context: project-intelligence/business | Priority: high | Version: 1.0 | Updated: 2025-01-12 -->
|
||||
|
||||
# Business Domain
|
||||
|
||||
> Document the business context, problems solved, and value created.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
- **Purpose**: Understand why this project exists
|
||||
- **Update When**: Business direction changes, new features shipped, pivot
|
||||
- **Audience**: Developers needing context, stakeholders, product team
|
||||
|
||||
## Project Identity
|
||||
|
||||
```
|
||||
Project Name: [Name]
|
||||
Tagline: [One-line description]
|
||||
Problem Statement: [What problem are we solving?]
|
||||
Solution: [How we're solving it]
|
||||
```
|
||||
|
||||
## Target Users
|
||||
|
||||
| User Segment | Who They Are | What They Need | Pain Points |
|
||||
|--------------|--------------|----------------|-------------|
|
||||
| [Primary] | [Description] | [Their needs] | [Their frustrations] |
|
||||
| [Secondary] | [Description] | [Their needs] | [Their frustrations] |
|
||||
|
||||
## Value Proposition
|
||||
|
||||
**For Users**:
|
||||
- [Key benefit 1]
|
||||
- [Key benefit 2]
|
||||
- [Key benefit 3]
|
||||
|
||||
**For Business**:
|
||||
- [Key value 1]
|
||||
- [Key value 2]
|
||||
|
||||
## Success Metrics
|
||||
|
||||
| Metric | Definition | Target | Current |
|
||||
|--------|------------|--------|---------|
|
||||
| [Metric 1] | [What it measures] | [Goal] | [Actual] |
|
||||
| [Metric 2] | [What it measures] | [Goal] | [Actual] |
|
||||
|
||||
## Business Model (if applicable)
|
||||
|
||||
```
|
||||
Revenue Model: [How the business makes money]
|
||||
Pricing Strategy: [If applicable]
|
||||
Unit Economics: [CAC, LTV, etc.]
|
||||
Market Position: [Where we fit in the market]
|
||||
```
|
||||
|
||||
## Key Stakeholders
|
||||
|
||||
| Role | Name | Responsibility | Contact |
|
||||
|------|------|----------------|---------|
|
||||
| [Product Owner] | [Name] | [What they own] | [Contact] |
|
||||
| [Tech Lead] | [Name] | [What they own] | [Contact] |
|
||||
| [Business Lead] | [Name] | [What they own] | [Contact] |
|
||||
|
||||
## Roadmap Context
|
||||
|
||||
**Current Focus**: [What we're working on now]
|
||||
**Next Milestone**: [Upcoming goal]
|
||||
**Long-term Vision**: [Where this is heading]
|
||||
|
||||
## Business Constraints
|
||||
|
||||
- [Constraint 1] - [Why it exists]
|
||||
- [Constraint 2] - [Why it exists]
|
||||
|
||||
## Onboarding Checklist
|
||||
|
||||
- [ ] Understand the problem statement
|
||||
- [ ] Identify target users and their needs
|
||||
- [ ] Know the key value proposition
|
||||
- [ ] Understand success metrics
|
||||
- [ ] Know who the stakeholders are
|
||||
- [ ] Understand current business constraints
|
||||
|
||||
## Related Files
|
||||
|
||||
- `technical-domain.md` - How this business need is solved technically
|
||||
- `business-tech-bridge.md` - Mapping between business and technical
|
||||
- `decisions-log.md` - Business decisions with context
|
||||
|
|
@ -0,0 +1,94 @@
|
|||
<!-- Context: project-intelligence/bridge | Priority: high | Version: 1.0 | Updated: 2025-01-12 -->
|
||||
|
||||
# Business ↔ Tech Bridge
|
||||
|
||||
> Document how business needs translate to technical solutions. This is the critical connection point.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
- **Purpose**: Show stakeholders technical choices serve business goals
|
||||
- **Purpose**: Show developers business constraints drive architecture
|
||||
- **Update When**: New features, refactoring, business pivot
|
||||
|
||||
## Core Mapping
|
||||
|
||||
| Business Need | Technical Solution | Why This Mapping | Business Value |
|
||||
|---------------|-------------------|------------------|----------------|
|
||||
| [Users need X] | [Technical implementation] | [Why this maps] | [Value delivered] |
|
||||
| [Business wants Y] | [Technical implementation] | [Why this maps] | [Value delivered] |
|
||||
| [Compliance requires Z] | [Technical implementation] | [Why this maps] | [Value delivered] |
|
||||
|
||||
## Feature Mapping Examples
|
||||
|
||||
### Feature: [Feature Name]
|
||||
|
||||
**Business Context**:
|
||||
- User need: [What users need]
|
||||
- Business goal: [Why this matters to business]
|
||||
- Priority: [Why this was prioritized]
|
||||
|
||||
**Technical Implementation**:
|
||||
- Solution: [What was built]
|
||||
- Architecture: [How it fits the system]
|
||||
- Trade-offs: [What was considered and why it won]
|
||||
|
||||
**Connection**:
|
||||
[Explain clearly how the technical solution serves the business need. What would happen without this feature? What does this feature enable for the business?]
|
||||
|
||||
### Feature: [Feature Name]
|
||||
|
||||
**Business Context**:
|
||||
- User need: [What users need]
|
||||
- Business goal: [Why this matters to business]
|
||||
- Priority: [Why this was prioritized]
|
||||
|
||||
**Technical Implementation**:
|
||||
- Solution: [What was built]
|
||||
- Architecture: [How it fits the system]
|
||||
- Trade-offs: [What was considered and why it won]
|
||||
|
||||
**Connection**:
|
||||
[Explain clearly how the technical solution serves the business need.]
|
||||
|
||||
## Trade-off Decisions
|
||||
|
||||
When business and technical needs conflict, document the trade-off:
|
||||
|
||||
| Situation | Business Priority | Technical Priority | Decision Made | Rationale |
|
||||
|-----------|-------------------|-------------------|---------------|-----------|
|
||||
| [Conflict] | [What business wants] | [What tech wants] | [What was chosen] | [Why this was right] |
|
||||
|
||||
## Common Misalignments
|
||||
|
||||
| Misalignment | Warning Signs | Resolution Approach |
|
||||
|--------------|---------------|---------------------|
|
||||
| [Type of mismatch] | [Symptoms to watch for] | [How to address] |
|
||||
|
||||
## Stakeholder Communication
|
||||
|
||||
This file helps translate between worlds:
|
||||
|
||||
**For Business Stakeholders**:
|
||||
- Shows that technical investments serve business goals
|
||||
- Provides context for why certain choices were made
|
||||
- Demonstrates ROI of technical decisions
|
||||
|
||||
**For Technical Stakeholders**:
|
||||
- Provides business context for architectural decisions
|
||||
- Shows the "why" behind constraints and requirements
|
||||
- Helps prioritize technical debt with business impact
|
||||
|
||||
## Onboarding Checklist
|
||||
|
||||
- [ ] Understand the core business needs this project addresses
|
||||
- [ ] See how each major feature maps to business value
|
||||
- [ ] Know the key trade-offs and why decisions were made
|
||||
- [ ] Be able to explain to stakeholders why technical choices matter
|
||||
- [ ] Be able to explain to developers why business constraints exist
|
||||
|
||||
## Related Files
|
||||
|
||||
- `business-domain.md` - Business needs in detail
|
||||
- `technical-domain.md` - Technical implementation in detail
|
||||
- `decisions-log.md` - Decisions made with full context
|
||||
- `living-notes.md` - Current open questions and issues
|
||||
130
.opencode/context/project-intelligence/decisions-log.md
Normal file
130
.opencode/context/project-intelligence/decisions-log.md
Normal file
|
|
@ -0,0 +1,130 @@
|
|||
<!-- Context: project-intelligence/decisions | Priority: high | Version: 1.0 | Updated: 2025-01-12 -->
|
||||
|
||||
# Decisions Log
|
||||
|
||||
> Record major architectural and business decisions with full context. This prevents "why was this done?" debates.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
- **Purpose**: Document decisions so future team members understand context
|
||||
- **Format**: Each decision as a separate entry
|
||||
- **Status**: Decided | Pending | Under Review | Deprecated
|
||||
|
||||
## Decision Template
|
||||
|
||||
```markdown
|
||||
## [Decision Title]
|
||||
|
||||
**Date**: YYYY-MM-DD
|
||||
**Status**: [Decided/Pending/Under Review/Deprecated]
|
||||
**Owner**: [Who owns this decision]
|
||||
|
||||
### Context
|
||||
[What situation prompted this decision? What was the problem or opportunity?]
|
||||
|
||||
### Decision
|
||||
[What was decided? Be specific about the choice made.]
|
||||
|
||||
### Rationale
|
||||
[Why this decision? What were the alternatives and why were they rejected?]
|
||||
|
||||
### Alternatives Considered
|
||||
| Alternative | Pros | Cons | Why Rejected? |
|
||||
|-------------|------|------|---------------|
|
||||
| [Alt 1] | [Pros] | [Cons] | [Why not chosen] |
|
||||
| [Alt 2] | [Pros] | [Cons] | [Why not chosen] |
|
||||
|
||||
### Impact
|
||||
**Positive**: [What this enables or improves]
|
||||
**Negative**: [What trade-offs or limitations this creates]
|
||||
**Risk**: [What could go wrong]
|
||||
|
||||
### Related
|
||||
- [Links to related decisions, PRs, issues, or documentation]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Decision: [Title]
|
||||
|
||||
**Date**: YYYY-MM-DD
|
||||
**Status**: [Status]
|
||||
**Owner**: [Owner]
|
||||
|
||||
### Context
|
||||
[What was happening? Why did we need to decide?]
|
||||
|
||||
### Decision
|
||||
[What we decided]
|
||||
|
||||
### Rationale
|
||||
[Why this was the right choice]
|
||||
|
||||
### Alternatives Considered
|
||||
| Alternative | Pros | Cons | Why Rejected? |
|
||||
|-------------|------|------|---------------|
|
||||
| [Option A] | [Good things] | [Bad things] | [Reason] |
|
||||
| [Option B] | [Good things] | [Bad things] | [Reason] |
|
||||
|
||||
### Impact
|
||||
- **Positive**: [What we gain]
|
||||
- **Negative**: [What we trade off]
|
||||
- **Risk**: [What to watch for]
|
||||
|
||||
### Related
|
||||
- [Link to PR #000]
|
||||
- [Link to issue #000]
|
||||
- [Link to documentation]
|
||||
|
||||
---
|
||||
|
||||
## Decision: [Title]
|
||||
|
||||
**Date**: YYYY-MM-DD
|
||||
**Status**: [Status]
|
||||
**Owner**: [Owner]
|
||||
|
||||
### Context
|
||||
[What was happening?]
|
||||
|
||||
### Decision
|
||||
[What we decided]
|
||||
|
||||
### Rationale
|
||||
[Why this was right]
|
||||
|
||||
### Alternatives Considered
|
||||
| Alternative | Pros | Cons | Why Rejected? |
|
||||
|-------------|------|------|---------------|
|
||||
| [Option A] | [Good things] | [Bad things] | [Reason] |
|
||||
|
||||
### Impact
|
||||
- **Positive**: [What we gain]
|
||||
- **Negative**: [What we trade off]
|
||||
|
||||
### Related
|
||||
- [Link]
|
||||
|
||||
---
|
||||
|
||||
## Deprecated Decisions
|
||||
|
||||
Decisions that were later overturned (for historical context):
|
||||
|
||||
| Decision | Date | Replaced By | Why |
|
||||
|----------|------|-------------|-----|
|
||||
| [Old decision] | [Date] | [New decision] | [Reason] |
|
||||
|
||||
## Onboarding Checklist
|
||||
|
||||
- [ ] Understand the philosophy behind major architectural choices
|
||||
- [ ] Know why certain technologies were chosen over alternatives
|
||||
- [ ] Understand trade-offs that were made
|
||||
- [ ] Know where to find decision context when questions arise
|
||||
- [ ] Understand what decisions are pending and why
|
||||
|
||||
## Related Files
|
||||
|
||||
- `technical-domain.md` - Technical implementation affected by these decisions
|
||||
- `business-tech-bridge.md` - How decisions connect business and technical
|
||||
- `living-notes.md` - Current open questions that may become decisions
|
||||
114
.opencode/context/project-intelligence/living-notes.md
Normal file
114
.opencode/context/project-intelligence/living-notes.md
Normal file
|
|
@ -0,0 +1,114 @@
|
|||
<!-- Context: project-intelligence/notes | Priority: high | Version: 1.0 | Updated: 2025-01-12 -->
|
||||
|
||||
# Living Notes
|
||||
|
||||
> Active issues, technical debt, open questions, and insights that don't fit elsewhere. Keep this alive.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
- **Purpose**: Capture current state, problems, and open questions
|
||||
- **Update**: Weekly or when status changes
|
||||
- **Archive**: Move resolved items to bottom with status
|
||||
|
||||
## Technical Debt
|
||||
|
||||
| Item | Impact | Priority | Mitigation |
|
||||
|------|--------|----------|------------|
|
||||
| [Debt item] | [What risk it creates] | [High/Med/Low] | [How to manage] |
|
||||
|
||||
### Technical Debt Details
|
||||
|
||||
**[Debt Item]**
|
||||
*Priority*: [High/Med/Low]
|
||||
*Impact*: [What happens if not addressed]
|
||||
*Root Cause*: [Why this debt exists]
|
||||
*Proposed Solution*: [How to fix it]
|
||||
*Effort*: [Small/Medium/Large]
|
||||
*Status*: [Acknowledged | Scheduled | In Progress | Deferred]
|
||||
|
||||
## Open Questions
|
||||
|
||||
| Question | Stakeholders | Status | Next Action |
|
||||
|----------|--------------|--------|-------------|
|
||||
| [Question] | [Who needs to decide] | [Open/In Progress] | [What needs to happen] |
|
||||
|
||||
### Open Question Details
|
||||
|
||||
**[Question]**
|
||||
*Context*: [Why this question matters]
|
||||
*Stakeholders*: [Who needs to be involved]
|
||||
*Options*: [What are the possibilities]
|
||||
*Timeline*: [When does this need resolution]
|
||||
*Status*: [Open/In Progress/Blocked]
|
||||
|
||||
## Known Issues
|
||||
|
||||
| Issue | Severity | Workaround | Status |
|
||||
|-------|----------|------------|--------|
|
||||
| [Issue] | [Critical/High/Med/Low] | [Temporary fix] | [Known/In Progress/Fixed] |
|
||||
|
||||
### Issue Details
|
||||
|
||||
**[Issue Title]**
|
||||
*Severity*: [Critical/High/Med/Low]
|
||||
*Impact*: [Who/what is affected]
|
||||
*Reproduction*: [Steps to reproduce if applicable]
|
||||
*Workaround*: [Temporary solution if exists]
|
||||
*Root Cause*: [If known]
|
||||
*Fix Plan*: [How to properly fix]
|
||||
*Status*: [Known/In Progress/Fixed in vX.X]
|
||||
|
||||
## Insights & Lessons Learned
|
||||
|
||||
### What Works Well
|
||||
- [Positive pattern 1] - [Why it works]
|
||||
- [Positive pattern 2] - [Why it works]
|
||||
|
||||
### What Could Be Better
|
||||
- [Area for improvement 1] - [Why it's a problem]
|
||||
- [Area for improvement 2] - [Why it's a problem]
|
||||
|
||||
### Lessons Learned
|
||||
- [Lesson 1] - [Context and implication]
|
||||
- [Lesson 2] - [Context and implication]
|
||||
|
||||
## Patterns & Conventions
|
||||
|
||||
### Code Patterns Worth Preserving
|
||||
- [Pattern 1] - [Where it lives, why it's good]
|
||||
- [Pattern 2] - [Where it lives, why it's good]
|
||||
|
||||
### Gotchas for Maintainers
|
||||
- [Gotcha 1] - [What to watch out for]
|
||||
- [Gotcha 2] - [What to watch out for]
|
||||
|
||||
## Active Projects
|
||||
|
||||
| Project | Goal | Owner | Timeline |
|
||||
|---------|------|-------|----------|
|
||||
| [Project] | [What we're doing] | [Who owns it] | [When it matters] |
|
||||
|
||||
## Archive (Resolved Items)
|
||||
|
||||
Moved here for historical reference. Current team should refer to current notes above.
|
||||
|
||||
### Resolved: [Item]
|
||||
- **Resolved**: [Date]
|
||||
- **Resolution**: [What was decided/done]
|
||||
- **Learnings**: [What we learned from this]
|
||||
|
||||
## Onboarding Checklist
|
||||
|
||||
- [ ] Review known technical debt and understand impact
|
||||
- [ ] Know what open questions exist and who's involved
|
||||
- [ ] Understand current issues and workarounds
|
||||
- [ ] Be aware of patterns and gotchas
|
||||
- [ ] Know active projects and timelines
|
||||
- [ ] Understand the team's priorities
|
||||
|
||||
## Related Files
|
||||
|
||||
- `decisions-log.md` - Past decisions that inform current state
|
||||
- `business-domain.md` - Business context for current priorities
|
||||
- `technical-domain.md` - Technical context for current state
|
||||
- `business-tech-bridge.md` - Context for current trade-offs
|
||||
65
.opencode/context/project-intelligence/navigation.md
Normal file
65
.opencode/context/project-intelligence/navigation.md
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
<!-- Context: project-intelligence/nav | Priority: high | Version: 1.0 | Updated: 2025-01-12 -->
|
||||
|
||||
# Project Intelligence
|
||||
|
||||
> Start here for quick project understanding. These files bridge business and technical domains.
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
.opencode/context/project-intelligence/
|
||||
├── navigation.md # This file - quick overview
|
||||
├── business-domain.md # Business context and problem statement
|
||||
├── technical-domain.md # Stack, architecture, technical decisions
|
||||
├── business-tech-bridge.md # How business needs map to solutions
|
||||
├── decisions-log.md # Major decisions with rationale
|
||||
└── living-notes.md # Active issues, debt, open questions
|
||||
```
|
||||
|
||||
## Quick Routes
|
||||
|
||||
| What You Need | File | Description |
|
||||
|---------------|------|-------------|
|
||||
| Understand the "why" | `business-domain.md` | Problem, users, value proposition |
|
||||
| Understand the "how" | `technical-domain.md` | Stack, architecture, integrations |
|
||||
| See the connection | `business-tech-bridge.md` | Business → technical mapping |
|
||||
| Know the context | `decisions-log.md` | Why decisions were made |
|
||||
| Current state | `living-notes.md` | Active issues and open questions |
|
||||
| All of the above | Read all files in order | Full project intelligence |
|
||||
|
||||
## Usage
|
||||
|
||||
**New Team Member / Agent**:
|
||||
1. Start with `navigation.md` (this file)
|
||||
2. Read all files in order for complete understanding
|
||||
3. Follow onboarding checklist in each file
|
||||
|
||||
**Quick Reference**:
|
||||
- Business focus → `business-domain.md`
|
||||
- Technical focus → `technical-domain.md`
|
||||
- Decision context → `decisions-log.md`
|
||||
|
||||
## Integration
|
||||
|
||||
This folder is referenced from:
|
||||
- `.opencode/context/core/standards/project-intelligence.md` (standards and patterns)
|
||||
- `.opencode/context/core/system/context-guide.md` (context loading)
|
||||
|
||||
See `.opencode/context/core/context-system.md` for the broader context architecture.
|
||||
|
||||
## Maintenance
|
||||
|
||||
Keep this folder current:
|
||||
- Update when business direction changes
|
||||
- Document decisions as they're made
|
||||
- Review `living-notes.md` regularly
|
||||
- Archive resolved items from decisions-log.md
|
||||
|
||||
**Management Guide**: See `.opencode/context/core/standards/project-intelligence-management.md` for complete lifecycle management including:
|
||||
- How to update, add, and remove files
|
||||
- How to create new subfolders
|
||||
- Version tracking and frontmatter standards
|
||||
- Quality checklists and anti-patterns
|
||||
- Governance and ownership
|
||||
|
||||
See `.opencode/context/core/standards/project-intelligence.md` for the standard itself.
|
||||
108
.opencode/context/project-intelligence/technical-domain.md
Normal file
108
.opencode/context/project-intelligence/technical-domain.md
Normal file
|
|
@ -0,0 +1,108 @@
|
|||
<!-- Context: project-intelligence/technical | Priority: high | Version: 1.0 | Updated: 2025-01-12 -->
|
||||
|
||||
# Technical Domain
|
||||
|
||||
> Document the technical foundation, architecture, and key decisions.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
- **Purpose**: Understand how the project works technically
|
||||
- **Update When**: New features, refactoring, tech stack changes
|
||||
- **Audience**: Developers, DevOps, technical stakeholders
|
||||
|
||||
## Primary Stack
|
||||
|
||||
| Layer | Technology | Version | Rationale |
|
||||
|-------|-----------|---------|-----------|
|
||||
| Language | [e.g., TypeScript] | [Version] | [Why this language] |
|
||||
| Framework | [e.g., Node.js] | [Version] | [Why this framework] |
|
||||
| Database | [e.g., PostgreSQL] | [Version] | [Why this database] |
|
||||
| Infrastructure | [e.g., AWS, Vercel] | [N/A] | [Why this infra] |
|
||||
| Key Libraries | [List important ones] | [Versions] | [Why each matters] |
|
||||
|
||||
## Architecture Pattern
|
||||
|
||||
```
|
||||
Type: [Monolith | Microservices | Serverless | Agent-based | Hybrid]
|
||||
Pattern: [Brief description]
|
||||
Diagram: [Link to architecture diagram if exists]
|
||||
```
|
||||
|
||||
### Why This Architecture?
|
||||
|
||||
[Explain the business and technical reasons for this architecture choice. What problem does this architecture solve? What were alternatives considered?]
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
[Project Root]
|
||||
├── src/ # Source code
|
||||
├── tests/ # Test files
|
||||
├── docs/ # Documentation
|
||||
├── scripts/ # Build/deploy scripts
|
||||
└── [Other key directories]
|
||||
```
|
||||
|
||||
**Key Directories**:
|
||||
- `src/` - Contains all application logic organized by [module/feature/domain]
|
||||
- `tests/` - [How tests are organized]
|
||||
- `docs/` - [What documentation lives here]
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
| Decision | Rationale | Impact |
|
||||
|----------|-----------|--------|
|
||||
| [Decision 1] | [Why this choice] | [What it enables] |
|
||||
| [Decision 2] | [Why this choice] | [What it enables] |
|
||||
|
||||
See `decisions-log.md` for full decision history with alternatives.
|
||||
|
||||
## Integration Points
|
||||
|
||||
| System | Purpose | Protocol | Direction |
|
||||
|--------|---------|----------|-----------|
|
||||
| [API 1] | [What it does] | [REST/GraphQL/gRPC] | [Inbound/Outbound] |
|
||||
| [Database] | [What it stores] | [PostgreSQL/Mongo/etc] | [Internal] |
|
||||
| [Service] | [What it provides] | [HTTP/gRPC] | [Outbound] |
|
||||
|
||||
## Technical Constraints
|
||||
|
||||
| Constraint | Origin | Impact |
|
||||
|------------|--------|--------|
|
||||
| [Legacy systems] | [Business/Tech] | [What limitation it creates] |
|
||||
| [Compliance] | [Regulation] | [What must be followed] |
|
||||
| [Performance] | [SLAs] | [What must be met] |
|
||||
|
||||
## Development Environment
|
||||
|
||||
```
|
||||
Setup: [Quick setup command or link]
|
||||
Requirements: [What developers need installed]
|
||||
Local Dev: [How to run locally]
|
||||
Testing: [How to run tests]
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
```
|
||||
Environment: [Production/Staging/Development]
|
||||
Platform: [Where it deploys]
|
||||
CI/CD: [Pipeline used]
|
||||
Monitoring: [Tools for observability]
|
||||
```
|
||||
|
||||
## Onboarding Checklist
|
||||
|
||||
- [ ] Know the primary tech stack
|
||||
- [ ] Understand the architecture pattern and why it was chosen
|
||||
- [ ] Know the key project directories and their purpose
|
||||
- [ ] Understand major technical decisions and rationale
|
||||
- [ ] Know integration points and dependencies
|
||||
- [ ] Be able to set up local development environment
|
||||
- [ ] Know how to run tests and deploy
|
||||
|
||||
## Related Files
|
||||
|
||||
- `business-domain.md` - Why this technical foundation exists
|
||||
- `business-tech-bridge.md` - How business needs map to technical solutions
|
||||
- `decisions-log.md` - Full decision history with context
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
**Purpose**: OpenCode Agent System project-specific context
|
||||
|
||||
**Status**: ⚠️ Legacy - Consider migrating to `openagents-repo/`
|
||||
**Status**: ⛔ DEPRECATED - Migrated to `project-intelligence/`
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -10,17 +10,15 @@
|
|||
|
||||
| File | Purpose | Status |
|
||||
|------|---------|--------|
|
||||
| `project-context.md` | Technology stack, patterns, workflows | ⚠️ Outdated |
|
||||
| `project-context.md` | Technology stack, patterns, workflows | ⛔ DEPRECATED |
|
||||
|
||||
---
|
||||
|
||||
## Note
|
||||
|
||||
This category contains legacy project context that may be redundant with:
|
||||
- `openagents-repo/` - Repository-specific context
|
||||
- `core/` - Universal standards and workflows
|
||||
This category is DEPRECATED. Its contents have been migrated to the Project Intelligence system.
|
||||
|
||||
**Recommendation**: Review and migrate useful content to appropriate categories.
|
||||
**Replacement**: See `.opencode/context/project-intelligence/navigation.md` for current project context.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,9 @@
|
|||
# OpenCode Agent System Project Context
|
||||
<!-- DEPRECATED: 2026-01-12 - Replaced by project-intelligence/technical-domain.md -->
|
||||
<!-- REPLACED BY: ../project-intelligence/technical-domain.md -->
|
||||
|
||||
# ⚠️ DEPRECATED: OpenCode Agent System Project Context
|
||||
|
||||
> ⛔ This file is deprecated. See `project-intelligence/technical-domain.md` for the current technical domain documentation.
|
||||
|
||||
## Technology Stack
|
||||
|
||||
|
|
|
|||
124
registry.json
124
registry.json
|
|
@ -754,11 +754,11 @@
|
|||
"name": "Project Context",
|
||||
"type": "context",
|
||||
"path": ".opencode/context/project/project-context.md",
|
||||
"description": "Project-specific context and configuration",
|
||||
"description": "⛔ DEPRECATED: Replaced by project-intelligence/technical-domain.md",
|
||||
"tags": [
|
||||
"deprecated",
|
||||
"context",
|
||||
"project",
|
||||
"configuration"
|
||||
"project"
|
||||
],
|
||||
"dependencies": [],
|
||||
"category": "essential"
|
||||
|
|
@ -2307,6 +2307,120 @@
|
|||
"tags": [],
|
||||
"dependencies": [],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "project-intelligence",
|
||||
"name": "Project Intelligence",
|
||||
"type": "context",
|
||||
"path": ".opencode/context/core/standards/project-intelligence.md",
|
||||
"description": "What and why of project intelligence - bridging business and technical domains",
|
||||
"tags": [
|
||||
"project-intelligence",
|
||||
"onboarding",
|
||||
"business",
|
||||
"technical"
|
||||
],
|
||||
"dependencies": [],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "project-intelligence-management",
|
||||
"name": "Project Intelligence Management",
|
||||
"type": "context",
|
||||
"path": ".opencode/context/core/standards/project-intelligence-management.md",
|
||||
"description": "How to manage project intelligence files - add, update, remove, version",
|
||||
"tags": [
|
||||
"project-intelligence",
|
||||
"management",
|
||||
"lifecycle"
|
||||
],
|
||||
"dependencies": [],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "project-intelligence-nav",
|
||||
"name": "Project Intelligence Navigation",
|
||||
"type": "context",
|
||||
"path": ".opencode/context/project-intelligence/navigation.md",
|
||||
"description": "Quick overview and routes for project intelligence files",
|
||||
"tags": [
|
||||
"project-intelligence",
|
||||
"navigation"
|
||||
],
|
||||
"dependencies": [],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "project-intelligence-business",
|
||||
"name": "Business Domain",
|
||||
"type": "context",
|
||||
"path": ".opencode/context/project-intelligence/business-domain.md",
|
||||
"description": "Business context, problems solved, target users, and value proposition",
|
||||
"tags": [
|
||||
"project-intelligence",
|
||||
"business",
|
||||
"domain"
|
||||
],
|
||||
"dependencies": [],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "project-intelligence-technical",
|
||||
"name": "Technical Domain",
|
||||
"type": "context",
|
||||
"path": ".opencode/context/project-intelligence/technical-domain.md",
|
||||
"description": "Technical foundation, stack, architecture, and key decisions",
|
||||
"tags": [
|
||||
"project-intelligence",
|
||||
"technical",
|
||||
"architecture"
|
||||
],
|
||||
"dependencies": [],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "project-intelligence-bridge",
|
||||
"name": "Business Tech Bridge",
|
||||
"type": "context",
|
||||
"path": ".opencode/context/project-intelligence/business-tech-bridge.md",
|
||||
"description": "How business needs map to technical solutions",
|
||||
"tags": [
|
||||
"project-intelligence",
|
||||
"business",
|
||||
"technical",
|
||||
"mapping"
|
||||
],
|
||||
"dependencies": [],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "project-intelligence-decisions",
|
||||
"name": "Decisions Log",
|
||||
"type": "context",
|
||||
"path": ".opencode/context/project-intelligence/decisions-log.md",
|
||||
"description": "Major architectural and business decisions with full context",
|
||||
"tags": [
|
||||
"project-intelligence",
|
||||
"decisions",
|
||||
"context"
|
||||
],
|
||||
"dependencies": [],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "project-intelligence-notes",
|
||||
"name": "Living Notes",
|
||||
"type": "context",
|
||||
"path": ".opencode/context/project-intelligence/living-notes.md",
|
||||
"description": "Active issues, technical debt, open questions, and insights",
|
||||
"tags": [
|
||||
"project-intelligence",
|
||||
"issues",
|
||||
"debt",
|
||||
"notes"
|
||||
],
|
||||
"dependencies": [],
|
||||
"category": "standard"
|
||||
}
|
||||
],
|
||||
"config": [
|
||||
|
|
@ -2401,6 +2515,7 @@
|
|||
"context:project-context",
|
||||
"context:quick-start",
|
||||
"context:core/*",
|
||||
"context:project-intelligence/*",
|
||||
"context:adding-skill",
|
||||
"config:env-example",
|
||||
"config:readme"
|
||||
|
|
@ -2431,6 +2546,7 @@
|
|||
"context:project-context",
|
||||
"context:quick-start",
|
||||
"context:core/*",
|
||||
"context:project-intelligence/*",
|
||||
"context:adding-skill",
|
||||
"config:env-example",
|
||||
"config:readme"
|
||||
|
|
@ -2477,6 +2593,7 @@
|
|||
"context:project-context",
|
||||
"context:quick-start",
|
||||
"context:core/*",
|
||||
"context:project-intelligence/*",
|
||||
"context:adding-skill",
|
||||
"config:env-example",
|
||||
"config:readme"
|
||||
|
|
@ -2532,6 +2649,7 @@
|
|||
"context:project-context",
|
||||
"context:quick-start",
|
||||
"context:core/*",
|
||||
"context:project-intelligence/*",
|
||||
"context:adding-skill",
|
||||
"config:env-example",
|
||||
"config:readme"
|
||||
|
|
|
|||
Loading…
Reference in a new issue