diff --git a/.opencode/context/core/standards/navigation.md b/.opencode/context/core/standards/navigation.md index 959b849..adfff0e 100644 --- a/.opencode/context/core/standards/navigation.md +++ b/.opencode/context/core/standards/navigation.md @@ -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) diff --git a/.opencode/context/core/standards/project-intelligence-management.md b/.opencode/context/core/standards/project-intelligence-management.md new file mode 100644 index 0000000..8ec426d --- /dev/null +++ b/.opencode/context/core/standards/project-intelligence-management.md @@ -0,0 +1,249 @@ + + +# 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 + + ``` +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 + + +# 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 + + + # {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 + + + ``` +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 + +``` + +**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` diff --git a/.opencode/context/core/standards/project-intelligence.md b/.opencode/context/core/standards/project-intelligence.md new file mode 100644 index 0000000..730c26d --- /dev/null +++ b/.opencode/context/core/standards/project-intelligence.md @@ -0,0 +1,77 @@ + + +# 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` diff --git a/.opencode/context/project-intelligence/business-domain.md b/.opencode/context/project-intelligence/business-domain.md new file mode 100644 index 0000000..710b5ea --- /dev/null +++ b/.opencode/context/project-intelligence/business-domain.md @@ -0,0 +1,88 @@ + + +# 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 diff --git a/.opencode/context/project-intelligence/business-tech-bridge.md b/.opencode/context/project-intelligence/business-tech-bridge.md new file mode 100644 index 0000000..aad0816 --- /dev/null +++ b/.opencode/context/project-intelligence/business-tech-bridge.md @@ -0,0 +1,94 @@ + + +# 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 diff --git a/.opencode/context/project-intelligence/decisions-log.md b/.opencode/context/project-intelligence/decisions-log.md new file mode 100644 index 0000000..b37f8f3 --- /dev/null +++ b/.opencode/context/project-intelligence/decisions-log.md @@ -0,0 +1,130 @@ + + +# 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 diff --git a/.opencode/context/project-intelligence/living-notes.md b/.opencode/context/project-intelligence/living-notes.md new file mode 100644 index 0000000..1ab9e49 --- /dev/null +++ b/.opencode/context/project-intelligence/living-notes.md @@ -0,0 +1,114 @@ + + +# 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 diff --git a/.opencode/context/project-intelligence/navigation.md b/.opencode/context/project-intelligence/navigation.md new file mode 100644 index 0000000..d85b05e --- /dev/null +++ b/.opencode/context/project-intelligence/navigation.md @@ -0,0 +1,65 @@ + + +# 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. diff --git a/.opencode/context/project-intelligence/technical-domain.md b/.opencode/context/project-intelligence/technical-domain.md new file mode 100644 index 0000000..38e08b4 --- /dev/null +++ b/.opencode/context/project-intelligence/technical-domain.md @@ -0,0 +1,108 @@ + + +# 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 diff --git a/.opencode/context/project/navigation.md b/.opencode/context/project/navigation.md index bcf2d28..5d6266a 100644 --- a/.opencode/context/project/navigation.md +++ b/.opencode/context/project/navigation.md @@ -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. --- diff --git a/.opencode/context/project/project-context.md b/.opencode/context/project/project-context.md index c90da68..2b55719 100644 --- a/.opencode/context/project/project-context.md +++ b/.opencode/context/project/project-context.md @@ -1,4 +1,9 @@ -# OpenCode Agent System Project Context + + + +# ⚠️ DEPRECATED: OpenCode Agent System Project Context + +> ⛔ This file is deprecated. See `project-intelligence/technical-domain.md` for the current technical domain documentation. ## Technology Stack diff --git a/registry.json b/registry.json index bd92ed3..013c6ec 100644 --- a/registry.json +++ b/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"