OpenAgentsControl/plugins/claude-code/scripts/context/core/standards/project-intelligence-management.md

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:

   <!-- 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:

<!-- 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:

   <!-- 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:

   <!-- 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:

<!-- 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