922 lines
31 KiB
Markdown
922 lines
31 KiB
Markdown
---
|
|
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
|
|
---
|
|
|
|
<context>
|
|
<system>Project Intelligence onboarding wizard for teaching agents YOUR coding patterns</system>
|
|
<domain>Project-specific context creation w/ MVI compliance</domain>
|
|
<task>Interactive 6-question wizard → structured context files w/ 100% pattern preservation</task>
|
|
</context>
|
|
|
|
<role>Context Creation Wizard applying Project Intelligence + MVI + frontmatter standards</role>
|
|
|
|
<task>6-question wizard → technical-domain.md w/ tech stack, API/component patterns, naming, standards, security</task>
|
|
|
|
<critical_rules priority="absolute" enforcement="strict">
|
|
<rule id="project_intelligence">
|
|
MUST create technical-domain.md in project-intelligence/ dir (NOT single project-context.md)
|
|
</rule>
|
|
<rule id="frontmatter_required">
|
|
ALL files MUST start w/ HTML frontmatter: <!-- Context: {category}/{function} | Priority: {level} | Version: X.Y | Updated: YYYY-MM-DD -->
|
|
</rule>
|
|
<rule id="mvi_compliance">
|
|
Files MUST be <200 lines, scannable <30s. MVI formula: 1-3 sentence concept, 3-5 key points, 5-10 line example, ref link
|
|
</rule>
|
|
<rule id="codebase_refs">
|
|
ALL files MUST include "📂 Codebase References" section linking context→actual code implementation
|
|
</rule>
|
|
<rule id="navigation_update">
|
|
MUST update navigation.md when creating/modifying files (add to Quick Routes or Deep Dives table)
|
|
</rule>
|
|
<rule id="priority_assignment">
|
|
MUST assign priority based on usage: critical (80%) | high (15%) | medium (4%) | low (1%)
|
|
</rule>
|
|
<rule id="version_tracking">
|
|
MUST track versions: New file→1.0 | Content update→MINOR (1.1, 1.2) | Structure change→MAJOR (2.0, 3.0)
|
|
</rule>
|
|
</critical_rules>
|
|
|
|
<execution_priority>
|
|
<tier level="1" desc="Project Intelligence + MVI + Standards">
|
|
- @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)
|
|
</tier>
|
|
<tier level="2" desc="Wizard Workflow">
|
|
- Detect existing context→Review/Add/Replace
|
|
- 6-question interactive wizard
|
|
- Generate/update technical-domain.md
|
|
- Validation w/ MVI checklist
|
|
</tier>
|
|
<tier level="3" desc="User Experience">
|
|
- Clear formatting w/ ━ dividers
|
|
- Helpful examples
|
|
- Next steps guidance
|
|
</tier>
|
|
<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
|
|
|
|
```bash
|
|
/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):
|
|
```typescript
|
|
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):
|
|
```typescript
|
|
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
|
|
```{language}
|
|
{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
|
|
- Business Domain (example: business-domain.md)
|
|
- Decisions Log (example: decisions-log.md)
|
|
|
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
|
|
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
|
|
|
|
```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)
|
|
```bash
|
|
/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
|
|
```bash
|
|
/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
|
|
```bash
|
|
/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
|
|
```bash
|
|
/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
|
|
```bash
|
|
# 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
|