OpenWriterControle/.opencode/command/add-context.md
Darren Hinde 9625e43d92
feat: OpenCode-compliant agents with centralized metadata system (#151)
* chore: bump version to v0.8.0

* chore: update version to 0.7.1 instead of 0.8.0

* docs: expand comparison table with Oh My OpenCode and additional features

* backup: development context before reorganization

* refactor(context): reorganize development folder

- Remove 7 duplicate files (ui/design files exist in ui/web/)
- Remove 2 redundant READMEs (use navigation.md instead)
- Move react-patterns.md to frontend/react/
- Create frontend/react/navigation.md
- Update 4 navigation files (development, ui, frontend, frontend/react)
- Update developer profile (4 path changes: ui-styling-standards, design-systems, design-assets, animation-patterns)
- Update 3 core context files (visual-development.md, design-iteration.md, file-locations.md)

Result: 29 context files (down from 36), no duplicates, clean structure

Refs: REORGANIZATION_PLAN.md, REORGANIZATION_SUMMARY.md

* docs(context): add frontend delegation guide

- Create when-to-delegate.md with clear decision criteria
- Decision matrix for when to delegate vs. handle directly
- Common patterns and examples
- Red flags and green flags
- Frontend-specialist capabilities reference
- Update frontend and development navigation files

Helps orchestrators decide when to delegate UI work to frontend-specialist subagent.

* feat: enhance developer and advanced profiles with UI, development, and system builder context

- Developer profile: Add UI/UX patterns, development principles, design systems, React patterns, animation patterns, styling standards, and design assets
- Full profile: Add same UI/development context as developer profile for consistency
- Advanced profile: Add comprehensive system builder context including templates, guides, context system standards, and repository management context
- Update profile descriptions to reflect new capabilities
- All context files verified to exist and are properly referenced

* fix: remove duplicate context entries with incorrect paths

- Remove duplicate design-assets, ui-styling-standards, clean-code, animation-patterns, design-systems, react-patterns, and api-design entries that pointed to wrong paths
- Remove non-existent development-readme and mastra-ai-readme entries
- Keep only correct entries with proper file paths
- All registry paths now validated and correct

* feat: add add-context command to registry and all profiles

- Register add-context command in registry.json
- Add command:add-context to all 5 profiles (essential, developer, business, full, advanced)
- Update add-context.md to mention external-context files in .tmp/ directory
- Fix command dependencies to use context IDs instead of full paths
- All registry paths and dependencies validated

* feat: enhance add-context with external context file management

- Add Stage 0: Detect external context files in .tmp/
- Offer options to extract, manage, or harvest external files
- Extract patterns from external context files for use in project intelligence
- Provide management options: update, remove, clean, or harvest
- Add examples showing external context extraction and management
- Update troubleshooting with external context file handling
- Integrate with /context harvest command for permanent context organization

* fix: comprehensive context system audit and restructuring

- Fix 6 command documentation inconsistencies in add-context.md
  * Correct /add-context vs /context harvest command references
  * Simplify Stage 0 workflow from 4 to 2 options
  * Update examples to match actual behavior
  * Remove non-existent operations from delegation section
  * Fix troubleshooting Q&A section

- Restructure registry.json with 4 major improvements
  * Replace 31 duplicate 'navigation' IDs with unique IDs per subfolder
    - core-navigation, development-navigation, openagents-repo-navigation, etc.
  * Add context:openagents-repo/* to developer and full profiles
    - Developers now have repo-specific guides and examples
  * Remove context:to-be-consumed/* from essential, developer, business, full
    - Keep only in advanced profile for system builders
  * Properly scope mastra-ai context via wildcard patterns

Validation Results:
- Registry: 220/220 paths valid, 0 missing dependencies
- Profiles: All appropriately scoped with no duplicate IDs
- Standards: MVI compliance, frontmatter, structure verified
- No regressions: All tests passing

Fixes issues with context organization, command consistency, and profile coverage.

* feat: make agents OpenCode-compliant with centralized metadata system

- Remove invalid OpenCode fields from agent frontmatter (id, category, type, version, author, tags, dependencies, context, permissions)
- Keep only valid OpenCode fields (name, description, mode, temperature, tools, permission)
- Create centralized metadata file (.opencode/config/agent-metadata.json) for registry metadata
- Update auto-detect script to merge frontmatter + metadata into registry
- Fix YAML parsing errors (orphaned list items after valid fields)
- Add comprehensive documentation for new metadata system
- All 27 agents now OpenCode-compliant and callable by name

Fixes validation errors:
- Extra inputs are not permitted (9 fields)
- Invalid temperature type (string instead of number)

Benefits:
- OpenCode validation passes without errors
- Registry maintains complete metadata (id, name, category, tags, dependencies)
- Single source of truth for agent metadata
- Easier to maintain and update dependencies
- Backward compatible with existing tools

* fix: correct context dependency IDs to match registry

- Update context dependencies to use actual registry IDs
- Fix: context:core/standards/code → context:standards-code
- Fix: context:core/workflows/task-delegation → context:workflows-delegation
- Fix: context:delegation → context:delegation-ref
- Fix: context:review → context:review-ref
- Fix: invalid dependency in agent-metadata.md documentation
- All registry validation now passes

* chore: add navigation files and update workflow context

- Add navigation.md files for all context directories
- Update design-iteration.md and task-delegation.md workflows
- Clean up backup files from metadata fixes

* fix: install dependencies in validate-registry workflow

The validation script requires the 'glob' package which is in devDependencies.
CI was failing because dependencies were never installed before running validation.

* fix: show validation errors in CI logs

Use tee to display validation output in logs while also saving to file.
This makes debugging CI failures much easier.

* fix: remove duplicate pull_request trigger

The workflow was running twice (pull_request + pull_request_target) causing
duplicate checks. Keep only pull_request_target to support bot PRs and allow
writing to PR branches.

* chore: trigger CI re-run with fixed workflow

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-01-31 02:15:12 +00:00

28 KiB

description tags dependencies
Interactive wizard to add project patterns using Project Intelligence standard
context
onboarding
project-intelligence
wizard
subagent:context-organizer
context:core/context-system/standards/mvi.md
context:core/context-system/standards/frontmatter.md
context:core/standards/project-intelligence.md
Project Intelligence onboarding wizard for teaching agents YOUR coding patterns Project-specific context creation w/ MVI compliance Interactive 6-question wizard → structured context files w/ 100% pattern preservation

Context Creation Wizard applying Project Intelligence + MVI + frontmatter standards

6-question wizard → technical-domain.md w/ tech stack, API/component patterns, naming, standards, security

<critical_rules priority="absolute" enforcement="strict"> MUST create technical-domain.md in project-intelligence/ dir (NOT single project-context.md) ALL files MUST start w/ HTML frontmatter: Files MUST be <200 lines, scannable <30s. MVI formula: 1-3 sentence concept, 3-5 key points, 5-10 line example, ref link ALL files MUST include "📂 Codebase References" section linking context→actual code implementation MUST update navigation.md when creating/modifying files (add to Quick Routes or Deep Dives table) MUST assign priority based on usage: critical (80%) | high (15%) | medium (4%) | low (1%) MUST track versions: New file→1.0 | Content update→MINOR (1.1, 1.2) | Structure change→MAJOR (2.0, 3.0) </critical_rules>

<execution_priority> - @project_intelligence (technical-domain.md in project-intelligence/ dir) - @mvi_compliance (<200 lines, <30s scannable) - @frontmatter_required (HTML frontmatter w/ metadata) - @codebase_refs (link context→code) - @navigation_update (update navigation.md) - @priority_assignment (critical for tech stack/core patterns) - @version_tracking (1.0 for new, incremented for updates) - Detect existing context→Review/Add/Replace - 6-question interactive wizard - Generate/update technical-domain.md - Validation w/ MVI checklist - Clear formatting w/ ━ dividers - Helpful examples - Next steps guidance <conflict_resolution>Tier 1 always overrides Tier 2/3 - standards are non-negotiable</conflict_resolution> </execution_priority>


Purpose

Help users add project patterns using Project Intelligence standard. Easiest way to teach agents YOUR coding patterns.

Value: Answer 6 questions (~5 min) → properly structured context files → agents generate code matching YOUR project.

Standards: @project_intelligence + @mvi_compliance + @frontmatter_required + @codebase_refs

Note: External context files are stored in .tmp/ directory (e.g., .tmp/external-context.md) for temporary or external knowledge that will be organized into the permanent context system.

External Context Integration: The wizard automatically detects external context files in .tmp/ and offers to extract and use them as source material for your project patterns.


Usage

/add-context                 # Interactive wizard (recommended)
/add-context --update        # Update existing context
/add-context --tech-stack    # Add/update tech stack only
/add-context --patterns      # Add/update code patterns only

Quick Start

Run: /add-context

What happens:

  1. Checks for external context files in .tmp/ (if found, offers to extract)
  2. Checks for existing project intelligence
  3. Asks 6 questions (~5 min) OR reviews existing patterns
  4. Generates/updates technical-domain.md
  5. Agents now use YOUR patterns

6 Questions (~5 min):

  1. Tech stack?
  2. API endpoint example?
  3. Component example?
  4. Naming conventions?
  5. Code standards?
  6. Security requirements?

Done! Agents now use YOUR patterns.

Management Options:

  • Update patterns: /add-context --update
  • Manage external files: /context harvest (extract, organize, clean)
  • Harvest to permanent: /context harvest
  • Clean context: /context harvest (cleans up .tmp/ files)

Workflow

Stage 0: Check for External Context Files

Check: .tmp/ directory for external context files (e.g., .tmp/external-context.md, .tmp/context-*.md)

If external files found:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Found external context files in .tmp/
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Files found:
  📄 .tmp/external-context.md (2.4 KB)
  📄 .tmp/api-patterns.md (1.8 KB)
  📄 .tmp/component-guide.md (3.1 KB)

These files can be extracted and organized into permanent context.

Options:
  1. Continue with /add-context (ignore external files for now)
  2. Manage external files first (via /context harvest)

Choose [1/2]: _

If option 1 (Continue):

  • Proceed to Stage 1 (detect existing project intelligence)
  • External files remain in .tmp/ for later processing

If option 2 (Manage external files):

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Manage External Context Files
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

To manage external context files, use the /context command:

  /context harvest

This will:
  ✓ Extract knowledge from .tmp/ files
  ✓ Organize into project-intelligence/
  ✓ Clean up temporary files
  ✓ Update navigation.md

After harvesting, run /add-context again to create project intelligence.

Ready to harvest? [y/n]: _

If yes: Exit and run /context harvest If no: Continue with /add-context (Stage 1)


Stage 1: Detect Existing Context

Check: ~/.opencode/context/project-intelligence/

If exists:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Found existing project intelligence!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Files found:
  ✓ technical-domain.md (Version: 1.2, Updated: 2026-01-15)
  ✓ business-domain.md (Version: 1.0, Updated: 2026-01-10)
  ✓ navigation.md

Current patterns:
  📦 Tech Stack: Next.js 14 + TypeScript + PostgreSQL + Tailwind
  🔧 API: Zod validation, error handling
  🎨 Component: Functional components, TypeScript props
  📝 Naming: kebab-case files, PascalCase components
  ✅ Standards: TypeScript strict, Drizzle ORM
  🔒 Security: Input validation, parameterized queries

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Options:
  1. Review and update patterns (show each one)
  2. Add new patterns (keep all existing)
  3. Replace all patterns (start fresh, backup old)
  4. Cancel

Choose [1/2/3/4]: _

If not exists:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
No project intelligence found. Let's create it!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Will create:
  - project-intelligence/technical-domain.md (tech stack & patterns)
  - project-intelligence/navigation.md (quick overview)

Takes ~5 min. Follows @mvi_compliance (<200 lines).

Ready? [y/n]: _

Stage 1.5: Review Existing Patterns (if updating)

Only runs if user chose "Review and update" in Stage 1.

For each pattern, show current→ask Keep/Update/Remove:

Pattern 1: Tech Stack

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Pattern 1/6: Tech Stack
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Current:
  Framework: Next.js 14
  Language: TypeScript
  Database: PostgreSQL
  Styling: Tailwind

Options: 1. Keep | 2. Update | 3. Remove
Choose [1/2/3]: _

If '2': New tech stack: _

Pattern 2: API Pattern

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Pattern 2/6: API Pattern
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Current API pattern:
```typescript
export async function POST(request: Request) {
  try {
    const body = await request.json()
    const validated = schema.parse(body)
    return Response.json({ success: true })
  } catch (error) {
    return Response.json({ error: error.message }, { status: 400 })
  }
}

Options: 1. Keep | 2. Update | 3. Remove Choose [1/2/3]: _

If '2': Paste new API pattern: _


#### Pattern 3-6: Component, Naming, Standards, Security
*(Same format: show current→Keep/Update/Remove)*

**After reviewing all**:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Review Summary ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Changes: ✓ Tech Stack: Updated (Next.js 14 → Next.js 15) ✓ API: Kept ✓ Component: Updated (new pattern) ✓ Naming: Kept ✓ Standards: Updated (+2 new) ✓ Security: Kept

Version: 1.2 → 1.3 (content update per @version_tracking) Updated: 2026-01-29

Proceed? [y/n]: _


---

### Stage 2: Interactive Wizard (for new patterns)

#### Q1: Tech Stack

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Q 1/6: What's your tech stack? ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Examples:

  1. Next.js + TypeScript + PostgreSQL + Tailwind
  2. React + Python + MongoDB + Material-UI
  3. Vue + Go + MySQL + Bootstrap
  4. Other (describe)

Your tech stack: _


**Capture**: Framework, Language, Database, Styling

#### Q2: API Pattern

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Q 2/6: API endpoint example? ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Paste API endpoint from YOUR project (matches your API style).

Example (Next.js):

export async function POST(request: Request) {
  const body = await request.json()
  const validated = schema.parse(body)
  return Response.json({ success: true })
}

Your API pattern (paste or 'skip'): _


**Capture**: API endpoint, error handling, validation, response format

#### Q3: Component Pattern

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Q 3/6: Component example? ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Paste component from YOUR project.

Example (React):

interface UserCardProps { name: string; email: string }
export function UserCard({ name, email }: UserCardProps) {
  return <div className="rounded-lg border p-4">
    <h3>{name}</h3><p>{email}</p>
  </div>
}

Your component (paste or 'skip'): _


**Capture**: Component structure, props pattern, styling, TypeScript

#### Q4: Naming Conventions

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Q 4/6: Naming conventions? ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Examples: Files: kebab-case (user-profile.tsx) Components: PascalCase (UserProfile) Functions: camelCase (getUserProfile) Database: snake_case (user_profiles)

Your conventions: Files: _ Components: _ Functions: _ Database: _


#### Q5: Code Standards

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Q 5/6: Code standards? ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Examples:

  • TypeScript strict mode
  • Validate w/ Zod
  • Use Drizzle for DB queries
  • Prefer server components

Your standards (one/line, 'done' when finished):

  1. _

#### Q6: Security Requirements

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Q 6/6: Security requirements? ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Examples:

  • Validate all user input
  • Use parameterized queries
  • Sanitize before rendering
  • HTTPS only

Your requirements (one/line, 'done' when finished):

  1. _

---

### Stage 3: Generate/Update Context

**Preview**:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Preview: technical-domain.md ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Technical Domain

Purpose: Tech stack, architecture, development patterns for this project. Last Updated: 2026-01-29

Quick Reference

Update Triggers: Tech stack changes | New patterns | Architecture decisions Audience: Developers, AI agents

Primary Stack

Layer Technology Version Rationale
Framework {framework} {version} {why}
Language {language} {version} {why}
Database {database} {version} {why}
Styling {styling} {version} {why}

Code Patterns

API Endpoint

{user_api_pattern}

Component

{user_component_pattern}

Naming Conventions

Type Convention Example
Files {file_naming} {example}
Components {component_naming} {example}
Functions {function_naming} {example}
Database {db_naming} {example}

Code Standards

{user_code_standards}

Security Requirements

{user_security_requirements}

📂 Codebase References

Implementation: {detected_files} - {desc} Config: package.json, tsconfig.json

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Size: {line_count} lines (limit: 200 per @mvi_compliance) Status: ✅ MVI compliant

Save to: ~/.opencode/context/project-intelligence/technical-domain.md

Looks good? [y/n/edit]: _


**Actions**:
- Confirm: Write file per @project_intelligence
- Edit: Open in editor→validate after
- Update: Show diff→highlight new→confirm

---

### Stage 4: Validation & Creation

**Validation**:

Running validation...

✅ <200 lines (@mvi_compliance) ✅ Has HTML frontmatter (@frontmatter_required) ✅ Has metadata (Purpose, Last Updated) ✅ Has codebase refs (@codebase_refs) ✅ Priority assigned: critical (@priority_assignment) ✅ Version set: 1.0 (@version_tracking) ✅ MVI compliant (<30s scannable) ✅ No duplication

Creating files per @project_intelligence... ✓ technical-domain.md ✓ navigation.md (updated per @navigation_update)

Done!


---

### Stage 5: Confirmation & Next Steps

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✅ Project Intelligence created successfully! ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Files created: ~/.opencode/context/project-intelligence/technical-domain.md ~/.opencode/context/project-intelligence/navigation.md

Agents now use YOUR patterns automatically!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ What's next? ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  1. Test it: opencode --agent OpenCoder

    "Create API endpoint" (Uses YOUR pattern!)

  2. Review: cat ~/.opencode/context/project-intelligence/technical-domain.md

  3. Add business context: /add-context --business

  4. Build: opencode --agent OpenCoder > "Create user auth system"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 💡 Tip: Update context as project evolves ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

When you: Add library → /add-context --update Change patterns → /add-context --update Migrate tech → /add-context --update

Agents stay synced!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📚 Learn More ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  • Project Intelligence: .opencode/context/core/standards/project-intelligence.md
  • MVI Principles: .opencode/context/core/context-system/standards/mvi.md
  • Context System: CONTEXT_SYSTEM_GUIDE.md

---

## Implementation Details

### External Context Detection (Stage 0)

**Process**:
1. Check: `ls .tmp/external-context.md .tmp/context-*.md .tmp/*-context.md 2>/dev/null`
2. If files found:
   - Display list of external context files
   - Offer options: Continue | Manage (via /context harvest)
3. If option 1 (Continue):
   - Proceed to Stage 1 (detect existing project intelligence)
   - External files remain in .tmp/ for later processing via `/context harvest`
4. If option 2 (Manage):
   - Guide user to `/context harvest` command
   - Explain what harvest does (extract, organize, clean)
   - Exit add-context
   - User runs `/context harvest` to process external files
   - User runs `/add-context` again after harvest completes

### Pattern Detection (Stage 1)

**Process**:
1. Check: `ls ~/.opencode/context/project-intelligence/`
2. Read: `cat technical-domain.md` (if exists)
3. Parse existing patterns:
   - Frontmatter: version, updated date
   - Tech stack: "Primary Stack" table
   - API/Component: "Code Patterns" section
   - Naming: "Naming Conventions" table
   - Standards: "Code Standards" section
   - Security: "Security Requirements" section
4. Display summary
5. Offer options: Review/Add/Replace/Cancel

### Pattern Review (Stage 1.5)

**Per pattern**:
1. Show current value (parsed from file)
2. Ask: Keep | Update | Remove
3. If Update: Prompt for new value
4. Track changes in `changes_to_make[]`

**After all reviewed**:
1. Show summary
2. Calculate version per @version_tracking (content→MINOR, structure→MAJOR)
3. Confirm
4. Proceed to Stage 3

### Delegation to ContextOrganizer

```yaml
operation: create | update
template: technical-domain  # Project Intelligence template
target_directory: project-intelligence

# For create/update operations
user_responses:
  tech_stack: {framework, language, database, styling}
  api_pattern: string | null
  component_pattern: string | null
  naming_conventions: {files, components, functions, database}
  code_standards: string[]
  security_requirements: string[]
  
frontmatter:
  context: project-intelligence/technical
  priority: critical  # @priority_assignment (80% use cases)
  version: {calculated}  # @version_tracking
  updated: {current_date}

validation:
  max_lines: 200  # @mvi_compliance
  has_frontmatter: true  # @frontmatter_required
  has_codebase_references: true  # @codebase_refs
  navigation_updated: true  # @navigation_update

Note: External context file management (harvest, extract, organize) is handled by /context harvest command, not /add-context.

File Structure Inference

Based on tech stack, infer common structure:

Next.js: src/app/ components/ lib/ db/ React: src/components/ hooks/ utils/ api/ Express: src/routes/ controllers/ models/ middleware/


Success Criteria

User Experience:

  • Wizard complete <5 min
  • Next steps clear
  • Update process understood

File Quality:

  • @mvi_compliance (<200 lines, <30s scannable)
  • @frontmatter_required (HTML frontmatter)
  • @codebase_refs (codebase references section)
  • @priority_assignment (critical for tech stack)
  • @version_tracking (1.0 new, incremented updates)

System Integration:

  • @project_intelligence (technical-domain.md in project-intelligence/)
  • @navigation_update (navigation.md updated)
  • Agents load & use patterns
  • No duplication

Examples

Example 1: First Time (No Context)

/add-context

# Q1: Next.js + TypeScript + PostgreSQL + Tailwind
# Q2: [pastes Next.js API route]
# Q3: [pastes React component]
# Q4-6: [answers]

✅ Created: technical-domain.md, navigation.md

Example 2: Review & Update

/add-context

# Found existing → Choose "1. Review and update"
# Pattern 1: Tech Stack → Update (Next.js 14 → 15)
# Pattern 2-6: Keep

✅ Updated: Version 1.2 → 1.3

Example 3: Quick Update

/add-context --tech-stack

# Current: Next.js 15 + TypeScript + PostgreSQL + Tailwind
# New: Next.js 15 + TypeScript + PostgreSQL + Drizzle + Tailwind

✅ Version 1.4 → 1.5

Example 4: Extract External Context

/add-context

# Found external context files in .tmp/
#   📄 .tmp/external-context.md (2.4 KB)
#   📄 .tmp/api-patterns.md (1.8 KB)
# 
# Choose: 1. Extract & use these files
# 
# Extracted patterns:
#   ✓ Tech Stack: Next.js 15 + TypeScript + PostgreSQL + Tailwind
#   ✓ API Pattern: [from external-context.md]
#   ✓ Component: [from api-patterns.md]
#   ✓ Naming: kebab-case files, PascalCase components
#   ✓ Standards: TypeScript strict, Zod validation
#   ✓ Security: Input validation, parameterized queries
#
# ✅ Created: technical-domain.md (merged with external patterns)

Example 5: External Context Files Present

/add-context

# Found external context files in .tmp/
#   📄 .tmp/external-context.md (2.4 KB)
#   📄 .tmp/api-patterns.md (1.8 KB)
#
# Options:
#   1. Continue with /add-context (ignore external files for now)
#   2. Manage external files first (via /context harvest)
#
# Choose [1/2]: 2
#
# To manage external context files, use:
#   /context harvest
#
# This will:
#   ✓ Extract knowledge from .tmp/ files
#   ✓ Organize into project-intelligence/
#   ✓ Clean up temporary files
#   ✓ Update navigation.md
#
# After harvesting, run /add-context again.

Example 6: After Harvesting External Context

# After running: /context harvest

/add-context

# No external context files found in .tmp/
# Proceeding to detect existing project intelligence...
#
# ✅ Created: technical-domain.md (merged with harvested patterns)

Error Handling

Invalid Input:

⚠️ Invalid input
Expected: Tech stack description
Got: [empty]

Example: Next.js + TypeScript + PostgreSQL + Tailwind

File Too Large:

⚠️ Exceeds 200 lines (@mvi_compliance)
Current: 245 | Limit: 200

Simplify patterns or split into multiple files.

Invalid Syntax:

⚠️ Invalid code syntax in API pattern
Error: Unexpected token line 3

Check code & retry.

Tips

Keep Simple: Focus on most common patterns, add more later Use Real Examples: Paste actual code from YOUR project Update Regularly: Run /add-context --update when patterns change Test After: Build something simple to verify agents use patterns correctly


Troubleshooting

Q: Agents not using patterns? A: Check file exists, <200 lines. Run /context validate

Q: See what's in context? A: cat ~/.opencode/context/project-intelligence/technical-domain.md

Q: Multiple context files? A: Yes! Create in ~/.opencode/context/project-intelligence/. Agents load all.

Q: Remove pattern? A: Edit directly: nano ~/.opencode/context/project-intelligence/technical-domain.md

Q: Share w/ team? A: Yes! Commit ~/.opencode/context/project-intelligence/ to repo.

Q: Have external context files in .tmp/? A: Run /context harvest to extract and organize them into permanent context

Q: Want to clean up .tmp/ files? A: Run /context harvest to extract knowledge and clean up temporary files

Q: Move .tmp/ files to permanent context? A: Run /context harvest to extract and organize them

Q: Update external context files? A: Edit directly: nano .tmp/external-context.md then run /context harvest

Q: Remove specific external file? A: Delete directly: rm .tmp/external-context.md then run /context harvest


  • /context - Manage context files (harvest, organize, validate)
  • /context validate - Check integrity
  • /context map - View structure