Home Explore Help
Sign In
logic855
/
OpenAgentsControl
mirror of https://github.com/darrenhinde/OpenAgentsControl.git
1
0
Fork 0
Files Issues 0 Wiki
Tree: c799173dd0
Branches Tags
OpenAgentsCo...
/
.opencode
/
command
/
add-context.md

add-context.md 31 KB
History Raw

description: Interactive wizard to add project patterns using Project Intelligence standard tags: [context, onboarding, project-intelligence, wizard] dependencies:

  • 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

MUST create technical-domain.md in project-intelligence/ dir (NOT single project-context.md)


ALL files MUST start w/ HTML frontmatter: <!-- Context: {category}/{function} | Priority: {level} | Version: X.Y | Updated: YYYY-MM-DD -->


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)


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

Tier 1 always overrides Tier 2/3 - standards are non-negotiable

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, saves to project)
/add-context --update        # Update existing context
/add-context --tech-stack    # Add/update tech stack only
/add-context --patterns      # Add/update code patterns only
/add-context --global        # Save to global config (~/.config/opencode/) instead of project

Quick Start

Run: /add-context

What happens:

  1. Saves to .opencode/context/project-intelligence/ in your project (always local)
  2. Checks for external context files in .tmp/ (if found, offers to extract)
  3. Checks for existing project intelligence
  4. Asks 6 questions (~5 min) OR reviews existing patterns
  5. Shows full preview of files to be created before writing
  6. Generates/updates technical-domain.md + navigation.md
  7. 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.5: Resolve Context Location

Determine where project intelligence files should be saved. This runs BEFORE anything else.

Default behavior: Always use local .opencode/context/project-intelligence/. Override: --global flag saves to ~/.config/opencode/context/project-intelligence/ instead.

Resolution:

  1. If --global flag โ†’ $CONTEXT_DIR = ~/.config/opencode/context/project-intelligence/
  2. Otherwise โ†’ $CONTEXT_DIR = .opencode/context/project-intelligence/ (always local)

If .opencode/context/ doesn't exist yet, create it silently โ€” no prompt needed. The directory structure is part of the output shown in Stage 4.

Variable: $CONTEXT_DIR is set here and used in all subsequent stages.

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: $CONTEXT_DIR (set in Stage 0.5 โ€” either .opencode/context/project-intelligence/ or ~/.config/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)
  4. Cancel

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

If user chooses 3 (Replace all):

โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”
Replace All: Preview
โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”

Will BACKUP existing files to:
  .tmp/backup/project-intelligence-{timestamp}/
    โ† technical-domain.md (Version: 1.2)
    โ† business-domain.md (Version: 1.0)
    โ† navigation.md

Will DELETE and RECREATE:
  $CONTEXT_DIR/technical-domain.md (new Version: 1.0)
  $CONTEXT_DIR/navigation.md (new Version: 1.0)

Existing files backed up โ†’ you can restore from .tmp/backup/ if needed.

Proceed? [y/n]: _

If not exists:

โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”
No project intelligence found. Let's create it!
โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”

Saving to: $CONTEXT_DIR

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
โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”

<!-- Context: project-intelligence/technical | Priority: critical | Version: 1.0 | Updated: 2026-01-29 -->

# 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
```{language}
{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

Related Files

โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”

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

Save to: $CONTEXT_DIR/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


**navigation.md preview** (also created/updated):

โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” Preview: navigation.md โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”

Project Intelligence

File Description Priority
technical-domain.md Tech stack & patterns critical

โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”


**Full creation plan**:

โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” Files to write: โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”

CREATE $CONTEXT_DIR/technical-domain.md ({line_count} lines) CREATE $CONTEXT_DIR/navigation.md ({nav_line_count} lines)

Total: 2 files

Proceed? [y/n]: _


---

### Stage 5: Confirmation & Next Steps

โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” โœ… Project Intelligence created successfully! โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”

Files created: $CONTEXT_DIR/technical-domain.md $CONTEXT_DIR/navigation.md

Location: $CONTEXT_DIR Agents now use YOUR patterns automatically!

โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” What's next? โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”

  1. Test it: opencode --agent OpenCoder

    "Create API endpoint" (Uses YOUR pattern!)

  2. Review: cat $CONTEXT_DIR/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!

โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” ๐Ÿ’ก Tip: Global patterns โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”

Want the same patterns across ALL your projects? /add-context --global โ†’ Saves to ~/.config/opencode/context/project-intelligence/ โ†’ Acts as fallback for projects without local context

Already have global patterns? Bring them into this project: /context migrate

โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” ๐Ÿ“š 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 $CONTEXT_DIR/ (path determined in Stage 0.5)
  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

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:

System Integration:

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: 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 5: 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 (local) or cat ~/.config/opencode/context/project-intelligence/technical-domain.md (global)

Q: Multiple context files? A: Yes! Create in your project-intelligence directory. Agents load all.

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

Q: Share w/ team? A: Yes! Use local install (.opencode/context/project-intelligence/) and commit to repo. Team members get your patterns automatically.

Q: Local vs global? A: Local (.opencode/) = project-specific, committed to git, team-shared. Global (~/.config/opencode/) = personal defaults across all projects. Local overrides global.

Q: Installed globally but want project patterns? A: Run /add-context (defaults to local). Creates .opencode/context/project-intelligence/ in your project even if OAC was installed globally.

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

Related Commands

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