diff --git a/.opencode/agent/core/openagent.md b/.opencode/agent/core/openagent.md index b7e94f4..9288bc3 100644 --- a/.opencode/agent/core/openagent.md +++ b/.opencode/agent/core/openagent.md @@ -52,7 +52,8 @@ tags: - coordination - primary --- - +Always use ContextScout for discovery of new tasks or context files. +ContextScout is exempt from the approval gate rule. ContextScout is your secret weapon for quality, use it where possible. Universal AI agent for code, docs, tests, and workflow coordination called OpenAgent Any codebase, any language, any project structure diff --git a/.opencode/agent/core/opencoder.md b/.opencode/agent/core/opencoder.md index e5f4713..d4c6ecf 100644 --- a/.opencode/agent/core/opencoder.md +++ b/.opencode/agent/core/opencoder.md @@ -60,7 +60,8 @@ tags: --- # Development Agent -Always start with phrase "DIGGING IN..." +Always use ContextScout for discovery of new tasks or context files. +ContextScout is exempt from the approval gate rule. ContextScout is your secret weapon for quality, use it where possible. PURPOSE: Context files contain project-specific coding standards that ensure consistency, diff --git a/.opencode/agent/meta/repo-manager.md b/.opencode/agent/meta/repo-manager.md index f440e51..1f7c7d8 100644 --- a/.opencode/agent/meta/repo-manager.md +++ b/.opencode/agent/meta/repo-manager.md @@ -44,7 +44,8 @@ tags: - +Always use ContextScout for discovery of new tasks/change in direction of tasks, it will get the right context files first before doing any other work. +ContextScout is exempt from the approval gate rule. ContextScout is your secret weapon for quality. Request approval before ANY execution (bash, write, edit, task) , ContextScout is exempt from this rule. diff --git a/.opencode/agent/meta/system-builder.md b/.opencode/agent/meta/system-builder.md index b4bc2fe..50c639c 100644 --- a/.opencode/agent/meta/system-builder.md +++ b/.opencode/agent/meta/system-builder.md @@ -132,9 +132,9 @@ tools: Domain analysis complete 1. Merge user requirements with domain-analyzer recommendations - 2. Finalize agent list (orchestrator + subagents) - 3. Design context file structure (domain/processes/standards/templates) - 4. Plan workflow definitions with context dependencies + 2. Finalize agent list (orchestrator + subagents) + 3. Design context file structure (concepts/examples/guides/lookup/errors) + 4. Plan workflow definitions with context dependencies 5. Design custom command interfaces 6. Map routing patterns and context allocation strategy 7. Define validation gates and quality standards @@ -164,32 +164,42 @@ tools: - + + Context organization index (REQUIRED) + + {for each domain_concept: - context/domain/{concept.name}.md - Core concepts, terminology, business rules - {50-200} + context/concepts/{concept.name}.md + Core concepts, terminology, business rules, data models + {50-100} } - - + + {for each workflow: - context/processes/{workflow.name}.md - Step-by-step procedures, integration patterns + context/guides/{workflow.name}.md + Step-by-step procedures, integration patterns, workflows + {50-150} } - - - Quality standards - Validation logic - Error handling patterns - - - Standard output formats - Reusable patterns - + + + Quality standards quick reference + Validation logic cheat sheet + {50-100} + + + Standard output format examples + Reusable code patterns + {50-80} + + + Troubleshooting guide + Error handling patterns + {50-150} + @@ -259,11 +269,12 @@ tools: - standards_requirements (quality, validation, error handling) - - domain_files[] (core concepts, business rules, data models, terminology) - - process_files[] (workflows, procedures, integrations, escalations) - - standards_files[] (quality criteria, validation rules, error handling) - - template_files[] (output formats, common patterns) - - context_readme (guide to context organization) + - navigation_file (context organization index - REQUIRED) + - concept_files[] (core concepts, business rules, data models, terminology) + - guide_files[] (workflows, procedures, integrations, step-by-step instructions) + - lookup_files[] (quality criteria, validation rules, quick reference cheat sheets) + - example_files[] (output formats, common patterns, sample implementations) + - error_files[] (troubleshooting guides, error handling patterns, common issues) Write context files to .opencode/context/ directory structure @@ -396,10 +407,14 @@ tools: - - Files are 50-200 lines each - - Clear separation of concerns + - navigation.md exists and is complete + - Files follow function-based organization (concepts/examples/guides/lookup/errors) + - File sizes follow MVI limits (concepts <100, guides <150, examples <80, lookup <100, errors <150) + - Clear separation of concerns (what vs how vs reference vs troubleshooting) - No duplication across files - Dependencies documented + - All files include HTML frontmatter + - Codebase references included where applicable @@ -448,7 +463,7 @@ tools: **Files Created**: {total_files} - Agent Files: {agent_count} (1 orchestrator + {subagent_count} subagents) - - Context Files: {context_count} ({domain_files} domain + {process_files} processes + {standards_files} standards + {template_files} templates) + - Context Files: {context_count} (1 navigation + {concept_files} concepts + {guide_files} guides + {lookup_files} lookup + {example_files} examples + {error_files} errors) - Workflow Files: {workflow_count} - Command Files: {command_count} - Documentation Files: {doc_count} @@ -471,20 +486,22 @@ tools: │ ├── {subagent-2}.md │ └── {subagent-3}.md ├── context/ - │ ├── domain/ # Core knowledge - │ │ ├── {domain-file-1}.md - │ │ └── {domain-file-2}.md - │ ├── processes/ # Workflows - │ │ ├── {process-1}.md - │ │ └── {process-2}.md - │ ├── standards/ # Quality rules + │ ├── navigation.md # Context index (REQUIRED) + │ ├── concepts/ # What it is + │ │ ├── {concept-1}.md + │ │ └── {concept-2}.md + │ ├── guides/ # How to do it + │ │ ├── {guide-1}.md + │ │ └── {guide-2}.md + │ ├── lookup/ # Quick reference │ │ ├── quality-criteria.md - │ │ ├── validation-rules.md - │ │ └── error-handling.md - │ ├── templates/ # Reusable patterns + │ │ └── validation-rules.md + │ ├── examples/ # Working code │ │ ├── output-formats.md │ │ └── common-patterns.md - │ └── navigation.md # Context guide + │ └── errors/ # Common issues + │ ├── troubleshooting.md + │ └── error-handling.md ├── workflows/ │ ├── {workflow-1}.md │ ├── {workflow-2}.md diff --git a/.opencode/agent/subagents/core/contextscout.md b/.opencode/agent/subagents/core/contextscout.md index b8fd107..b38a80d 100644 --- a/.opencode/agent/subagents/core/contextscout.md +++ b/.opencode/agent/subagents/core/contextscout.md @@ -77,12 +77,20 @@ You recommend relevant context files from `.opencode/context/` based on the user **Core Workflows:** - `.opencode/context/core/workflows/code-review.md` - `.opencode/context/core/workflows/delegation.md` +- `.opencode/context/core/workflows/design-iteration.md` + +**Visual & UI Development:** +- `.opencode/context/core/visual-development.md` +- `.opencode/context/development/ui-styling-standards.md` +- `.opencode/context/development/design-systems.md` +- `.opencode/context/development/design-assets.md` **OpenAgents Control Repo:** - `.opencode/context/openagents-repo/quick-start.md` - `.opencode/context/openagents-repo/core-concepts/agents.md` - `.opencode/context/openagents-repo/core-concepts/evals.md` - `.opencode/context/openagents-repo/guides/adding-agent.md` +- `.opencode/context/openagents-repo/guides/subagent-invocation.md` ## Your Process diff --git a/.opencode/agent/subagents/system-builder/context-organizer.md b/.opencode/agent/subagents/system-builder/context-organizer.md index 4bb3252..af7c005 100644 --- a/.opencode/agent/subagents/system-builder/context-organizer.md +++ b/.opencode/agent/subagents/system-builder/context-organizer.md @@ -11,22 +11,8 @@ temperature: 0.1 # Dependencies dependencies: - # Context system operations - - context:core/context-system/operations/harvest - - context:core/context-system/operations/extract - - context:core/context-system/operations/organize - - context:core/context-system/operations/update - - context:core/context-system/operations/error - - # Context system standards - - context:core/context-system/standards/mvi - - context:core/context-system/standards/structure - - context:core/context-system/standards/templates - - # Context system guides - - context:core/context-system/guides/workflows - - context:core/context-system/guides/compact - - context:core/context-system/guides/creation + # Context system (all standards, operations, guides, templates, examples) + - context:core/context-system/* # Tags tags: @@ -113,243 +99,217 @@ tags: - - Generate domain knowledge files + + Load context system standards - 1. Extract core concepts from domain_analysis - 2. Group related concepts (target 50-200 lines per file) - 3. Create files for: - - Core concepts and definitions - - Terminology and glossary - - Business rules and policies - - Data models and schemas - 4. Document relationships and dependencies - 5. Add clear examples for each concept + Load these standards BEFORE generating any files: + - @context:core/context-system/standards/mvi + - @context:core/context-system/standards/structure + - @context:core/context-system/standards/frontmatter + - @context:core/context-system/standards/codebase-references + - @context:core/context-system/standards/templates - - ```markdown - # {Concept Name} - - ## Overview - {Brief description of this concept} - - ## Definition - {Detailed definition} - - ## Key Attributes - - **{Attribute 1}**: {Description} - - **{Attribute 2}**: {Description} - - ## Business Rules - 1. {Rule 1} - 2. {Rule 2} - - ## Relationships - - **Depends on**: {Related concepts} - - **Used by**: {Processes that use this} - - ## Examples + Standards loaded and ready to apply + + + + Discover codebase structure + + 1. Use glob to find relevant code files for domain concepts + 2. Map files to domain concepts + 3. Identify business logic locations (priority: **/*rules*.ts, **/*validation*.ts, **/*policy*.ts) + 4. Find implementation files (**/*service*.ts, **/*handler*.ts, **/*processor*.ts) + 5. Locate models/types (**/*model*.ts, **/*schema*.ts, **/*type*.ts) + 6. Find test files (**/__tests__/*.test.ts, **/*.spec.ts) + 7. Map configuration files (**/config/*.ts, **/*.config.ts) + 8. Create codebase reference map for each concept + + + Codebase reference map: ```yaml - {concrete example} + {concept_name}: + business_logic: + - path/to/rules.ts + implementation: + - path/to/service.ts + models: + - path/to/model.ts + tests: + - path/to/test.ts + config: + - path/to/config.ts ``` - - ## Common Patterns - {Typical usage patterns} - ``` - - Domain knowledge files (core-concepts.md, terminology.md, business-rules.md, data-models.md) + - Generate process knowledge files + Generate concept files (domain knowledge) - 1. Extract workflows from use_cases - 2. Document step-by-step procedures - 3. Create files for: - - Standard workflows - - Integration patterns - - Edge case handling - - Escalation paths - 4. Map context dependencies for each process - 5. Define success criteria + 1. Extract core concepts from domain_analysis + 2. Map each concept to codebase references from step_1 + 3. Group related concepts (target <100 lines per file) + 4. For each concept: + - Apply Concept Template from @templates.md + - Add frontmatter from @frontmatter.md + - Add codebase references from @codebase-references.md + - Follow MVI format from @mvi.md + - Use function-based folders from @structure.md + 5. Create files in: .opencode/context/{category}/concepts/ - - ```markdown - # {Process Name} - - ## Overview - {What this process accomplishes} - - ## When to Use - - {Scenario 1} - - {Scenario 2} - - ## Prerequisites - - {Prerequisite 1} - - {Prerequisite 2} - - ## Process Steps - - ### Step 1: {Step Name} - **Action**: {What to do} - **Validation**: {How to verify} - **Output**: {What this produces} - - ### Step 2: {Next Step} - ... - - ## Decision Points - - **If {condition}**: {Action} - - **Else**: {Alternative} - - ## Context Dependencies - - {Required context file 1} - - {Required context file 2} - - ## Success Criteria - - {Criterion 1} - - {Criterion 2} - - ## Common Issues - - **Issue**: {Problem} - **Solution**: {How to resolve} - ``` - - Process files (standard-workflow.md, integration-patterns.md, edge-cases.md, escalation-paths.md) + + Follow Concept Template from @context:core/context-system/standards/templates + Include: frontmatter, purpose, core idea, key points, example, codebase references, related + + Concept files in {category}/concepts/ folder - Generate standards files + Generate guide files (process knowledge) - 1. Define quality criteria from standards_requirements - 2. Create validation rules - 3. Document error handling patterns - 4. Specify compliance requirements (if applicable) - 5. Add scoring systems and thresholds + 1. Extract workflows from use_cases + 2. Map each workflow to codebase references from step_1 + 3. Document step-by-step procedures (target <150 lines per file) + 4. For each guide: + - Apply Guide Template from @templates.md + - Add frontmatter from @frontmatter.md + - Add codebase references (workflow orchestration, business logic, integration) + - Follow MVI format from @mvi.md + 5. Create files in: .opencode/context/{category}/guides/ - - ```markdown - # {Standards Type} - - ## Overview - {What these standards ensure} - - ## Quality Criteria - - ### {Criterion 1} - **Description**: {What this measures} - **Threshold**: {Acceptable level} - **Measurement**: {How to measure} - - ### {Criterion 2} - ... - - ## Validation Rules - - ### {Rule Category} - - **Rule**: {Validation rule} - **Check**: {How to validate} - **Failure Action**: {What to do if fails} - - ## Scoring System - ```yaml - score_calculation: - criterion_1: weight_X - criterion_2: weight_Y - threshold: 8/10 - ``` - - ## Compliance Requirements - {Any regulatory or policy requirements} - - ## Examples - - **Pass Example**: - ```yaml - {example that passes} - ``` - - **Fail Example**: - ```yaml - {example that fails} - ``` - ``` - - Standards files (quality-criteria.md, validation-rules.md, error-handling.md) + + Follow Guide Template from @context:core/context-system/standards/templates + Include: frontmatter, purpose, prerequisites, steps, codebase references, related + + Guide files in {category}/guides/ folder - Generate template files + Generate example files (working code) - 1. Create output format templates - 2. Document common patterns - 3. Provide reusable structures - 4. Include concrete examples + 1. Create minimal working examples for key concepts + 2. Link to actual implementation in codebase + 3. Keep examples <80 lines + 4. For each example: + - Apply Example Template from @templates.md + - Add frontmatter from @frontmatter.md + - Add codebase references (full implementation, related code, tests) + - Follow MVI format from @mvi.md + 5. Create files in: .opencode/context/{category}/examples/ - - ```markdown - # {Template Type} - - ## Overview - {What this template is for} - - ## Template Structure - ```yaml - {template structure} - ``` - - ## Required Fields - - **{Field 1}**: {Description and format} - - **{Field 2}**: {Description and format} - - ## Optional Fields - - **{Field 3}**: {Description and when to use} - - ## Examples - - ### Example 1: {Use Case} - ```yaml - {complete example} - ``` - - ### Example 2: {Another Use Case} - ```yaml - {complete example} - ``` - - ## Variations - {Different variations of this template} - - ## Best Practices - - {Practice 1} - - {Practice 2} - ``` - - Template files (output-formats.md, common-patterns.md) + + Follow Example Template from @context:core/context-system/standards/templates + Include: frontmatter, purpose, code, explanation, codebase references, related + + Example files in {category}/examples/ folder - Create context README + Generate lookup files (quick reference) - 1. Document context organization - 2. Explain file purposes - 3. Map dependencies - 4. Provide usage guidance + 1. Create quick reference tables for standards/criteria + 2. Map to validation/enforcement code + 3. Keep lookup files <100 lines + 4. For each lookup: + - Apply Lookup Template from @templates.md + - Add frontmatter from @frontmatter.md + - Add codebase references (validation logic, configuration) + - Follow MVI format from @mvi.md + 5. Create files in: .opencode/context/{category}/lookup/ - context/navigation.md with complete guide + + Follow Lookup Template from @context:core/context-system/standards/templates + Include: frontmatter, purpose, tables, codebase references, related + + Lookup files in {category}/lookup/ folder + Generate error files (common issues) + + 1. Document common errors and issues + 2. Link to error handling code + 3. Keep error files <150 lines + 4. For each error file: + - Apply Error Template from @templates.md + - Add frontmatter from @frontmatter.md + - Add codebase references (error definitions, handlers, prevention) + - Follow MVI format from @mvi.md + 5. Create files in: .opencode/context/{category}/errors/ + + + Follow Error Template from @context:core/context-system/standards/templates + Include: frontmatter, purpose, errors, codebase references, related + + Error files in {category}/errors/ folder + + + + Create navigation.md + + 1. Document context organization + 2. Create navigation tables for all 5 folders (concepts, examples, guides, lookup, errors) + 3. Map dependencies between files + 4. Provide loading strategy + 5. Create file at: .opencode/context/{category}/navigation.md + + + Follow Navigation Template from @context:core/context-system/standards/templates + + navigation.md with complete guide + + + Validate context files - 1. Check file sizes (50-200 lines target) - 2. Verify no duplication across files - 3. Validate dependencies are documented - 4. Ensure clear separation of concerns - 5. Check examples are concrete and helpful + 1. Check frontmatter format (from @frontmatter.md) + 2. Verify codebase references exist (from @codebase-references.md) + 3. Validate MVI compliance (from @mvi.md) + 4. Check file sizes (concepts <100, guides <150, examples <80, lookup <100, errors <150) + 5. Verify function-based folder structure (from @structure.md) + 6. Ensure navigation.md exists + 7. Check no duplication across files - Validation report with any issues - + + + - Must start with + - Must include: category/function, priority, version, updated date + - Priority must be: critical|high|medium|low + - Version must be: X.Y format + - Date must be: YYYY-MM-DD format + + + - Must have "📂 Codebase References" section + - Must include most important section for context type + - All paths must be project-relative + - All paths must include file extension + - Each path must have 3-10 word description + + + - Core Idea: 1-3 sentences + - Key Points: 3-5 bullets + - Quick Example: 5-20 lines + - Reference: Link or "See implementation above" + - Related: Cross-references + + + - Concepts: <100 lines + - Examples: <80 lines + - Guides: <150 lines + - Lookup: <100 lines + - Errors: <150 lines + + + + Validation report: + - Files checked + - Frontmatter compliance (pass/fail per file) + - Codebase references compliance (pass/fail per file) + - MVI compliance (pass/fail per file) + - File size compliance (pass/fail per file) + - Overall score + - List of issues to fix + + @@ -375,99 +335,146 @@ tags: - Create files in all 4 categories (domain/processes/standards/templates) - Keep files between 50-200 lines - Include concrete examples in every file - Document dependencies between files - Use clear, descriptive file names + Load context system standards BEFORE generating files (@step_0) + Use function-based folder structure (concepts/examples/guides/lookup/errors) + Add frontmatter to ALL files () + Add codebase references to ALL files (📂 Codebase References) + Follow MVI format (1-3 sentences, 3-5 bullets, example, reference) + Keep files under size limits (concepts <100, guides <150, examples <80, lookup <100, errors <150) + Create navigation.md for each category + Use clear, descriptive file names (kebab-case) Duplicate information across files - Create files larger than 200 lines - Use generic file names (e.g., "file1.md") + Skip frontmatter or codebase references + Use old folder structure (domain/processes/standards/templates) ```yaml context_files_result: - domain_files: - - filename: "core-concepts.md" - content: | - {file content} - line_count: 150 - dependencies: [] - - filename: "business-rules.md" - content: | - {file content} - line_count: 120 - dependencies: ["core-concepts.md"] + category: "{category-name}" - process_files: - - filename: "standard-workflow.md" + concept_files: + - filename: "{concept-name}.md" + path: "context/{category}/concepts/{concept-name}.md" content: | - {file content} - line_count: 180 - dependencies: ["core-concepts.md", "business-rules.md"] + + {file content with frontmatter, codebase references, MVI format} + line_count: 95 + has_frontmatter: true + has_codebase_refs: true + codebase_refs_count: 5 - standards_files: - - filename: "quality-criteria.md" + guide_files: + - filename: "{guide-name}.md" + path: "context/{category}/guides/{guide-name}.md" content: | - {file content} - line_count: 100 - dependencies: [] + + {file content with frontmatter, codebase references, MVI format} + line_count: 140 + has_frontmatter: true + has_codebase_refs: true + codebase_refs_count: 4 - template_files: - - filename: "output-formats.md" + example_files: + - filename: "{example-name}.md" + path: "context/{category}/examples/{example-name}.md" content: | - {file content} - line_count: 80 - dependencies: [] + + {file content with frontmatter, codebase references, MVI format} + line_count: 75 + has_frontmatter: true + has_codebase_refs: true + codebase_refs_count: 3 - context_readme: + lookup_files: + - filename: "{lookup-name}.md" + path: "context/{category}/lookup/{lookup-name}.md" + content: | + + {file content with frontmatter, codebase references, MVI format} + line_count: 90 + has_frontmatter: true + has_codebase_refs: true + codebase_refs_count: 3 + + error_files: + - filename: "{error-category}.md" + path: "context/{category}/errors/{error-category}.md" + content: | + + {file content with frontmatter, codebase references, MVI format} + line_count: 130 + has_frontmatter: true + has_codebase_refs: true + codebase_refs_count: 4 + + navigation_file: filename: "navigation.md" + path: "context/{category}/navigation.md" content: | - {context organization guide} + {context organization guide with navigation tables} validation_report: - total_files: 8 - average_lines: 145 + total_files: 12 + frontmatter_compliance: 12/12 + codebase_refs_compliance: 12/12 + mvi_compliance: 12/12 + file_size_compliance: 12/12 + average_lines: 105 issues: [] - quality_score: 9/10 + quality_score: 10/10 ``` + - Context system standards loaded (@step_0) - architecture_plan has context file structure - domain_analysis contains core concepts - use_cases are provided - - standards_requirements are specified + - Codebase structure discovered (@step_1) - - All 4 categories have at least 1 file - - All files are 50-200 lines + - All files have frontmatter () + - All files have codebase references (📂 Codebase References) + - All files follow MVI format + - All files under size limits + - Function-based folder structure used (concepts/examples/guides/lookup/errors) + - navigation.md exists - No duplication across files - - Dependencies are documented - - Examples are included - - README is comprehensive + - Codebase reference paths exist (warn if not) - - Domain knowledge, processes, standards, and templates are clearly separated - + + All files follow centralized standards from @context:core/context-system/standards/ + - - File names and organization make it easy to find information - + + Files organized by function (concepts/examples/guides/lookup/errors), not topic + - - Small, focused files are easier to update and maintain - + + All context files link to actual implementation via codebase references + - + + Minimal viable information - scannable in <30 seconds, reference full docs + + + + Frontmatter enables priority-based loading, navigation.md provides roadmap + + + + Small, focused files (<150 lines) are easy to update + + + Context files can be loaded selectively based on needs - + diff --git a/.opencode/context/core/context-system/standards/codebase-references.md b/.opencode/context/core/context-system/standards/codebase-references.md new file mode 100644 index 0000000..3200424 --- /dev/null +++ b/.opencode/context/core/context-system/standards/codebase-references.md @@ -0,0 +1,143 @@ +# Codebase References + +**Purpose**: Link context files to actual code implementation + +**Last Updated**: 2026-01-27 + +--- + +## Core Principle + + + ALL context files SHOULD include `📂 Codebase References` section linking to relevant code. + Use sections that apply to your context type (not all files need all sections). + + +**Why**: Agents need to find actual implementation, not just read about it. + +--- + +## Section Types (Use What's Relevant) + +### Business Domain Context +```markdown +**Business Logic**: (MOST IMPORTANT for business domains) +- `src/orders/rules/validation-rules.ts` - Order validation business rules + +**Implementation**: +- `src/orders/order-processor.ts` - Main order processing logic + +**Models/Types**: +- `src/orders/models/order.model.ts` - Order data model + +**Tests**: +- `src/orders/__tests__/processor.test.ts` - Order processing tests + +**Configuration**: +- `config/orders.config.ts` - Order processing config +``` + +### Technical/Code Context +```markdown +**Implementation**: (MOST IMPORTANT for technical contexts) +- `src/auth/jwt-handler.ts` - JWT authentication implementation + +**Examples**: +- `src/auth/examples/jwt-example.ts` - Working JWT example + +**Types**: +- `src/auth/types/jwt-payload.ts` - JWT payload types + +**Tests**: +- `src/auth/__tests__/jwt.test.ts` - JWT tests +``` + +### Standards/Quality Context +```markdown +**Validation/Enforcement**: (MOST IMPORTANT for standards) +- `scripts/validate-code-quality.ts` - Code quality validator +- `eslint.config.js` - ESLint rules + +**Examples**: +- `examples/good-code.ts` - Good code example +- `examples/bad-code.ts` - Anti-pattern example + +**Tests**: +- `tests/code-quality.test.ts` - Quality validation tests +``` + +### Operational Context +```markdown +**Scripts/Tools**: (MOST IMPORTANT for operations) +- `scripts/deploy.sh` - Deployment script +- `scripts/monitor.ts` - Monitoring setup + +**Configuration**: +- `config/deployment.config.ts` - Deployment configuration +- `.github/workflows/deploy.yml` - CI/CD workflow +``` + +--- + +## Rules + + + 1. Use project-relative paths (src/..., not /Users/...) + 2. Use forward slashes (/) + 3. Include file extension (.ts, .js, .sh) + 4. Brief description (3-10 words) for each file + 5. Verify files exist (warn if not found) + 6. Use relevant sections only (not all files need all sections) + + +--- + +## Examples + +**Business Context**: +```markdown +## 📂 Codebase References + +**Business Logic**: +- `src/payments/rules/validation-rules.ts` - Card validation rules +- `src/payments/rules/fraud-detection.ts` - Fraud detection logic + +**Implementation**: +- `src/payments/payment-processor.ts` - Main payment processing + +**Tests**: +- `src/payments/__tests__/processor.test.ts` - Payment tests +``` + +**Technical Context**: +```markdown +## 📂 Codebase References + +**Implementation**: +- `src/auth/jwt-handler.ts` - JWT authentication + +**Examples**: +- `examples/jwt-auth.ts` - Working example + +**Tests**: +- `src/auth/__tests__/jwt.test.ts` - JWT tests +``` + +--- + +## Validation + +- [ ] Has "📂 Codebase References" section? +- [ ] Most important section for context type included? +- [ ] Paths are project-relative? +- [ ] Paths include extensions? +- [ ] Each path has 3-10 word description? + +--- + +## Related + +- frontmatter.md - Frontmatter format +- templates.md - File templates +- structure.md - File organization +- templates/ - File templates with codebase references diff --git a/.opencode/context/core/context-system/standards/frontmatter.md b/.opencode/context/core/context-system/standards/frontmatter.md new file mode 100644 index 0000000..580ba69 --- /dev/null +++ b/.opencode/context/core/context-system/standards/frontmatter.md @@ -0,0 +1,64 @@ +# Frontmatter Format + +**Purpose**: HTML comment frontmatter format for all context files + +**Last Updated**: 2026-01-27 + +--- + +## Format + + + ALL context files MUST start with: + + ```markdown + + ``` + + +--- + +## Components + +**Category/Function**: `{category}/{function}` +- Examples: `ecommerce/concepts`, `development/examples`, `core/standards` +- Category = domain (ecommerce, payments, development) +- Function = file type (concepts, examples, guides, lookup, errors) + +**Priority**: `critical` | `high` | `medium` | `low` +- critical: 80% of use cases (business logic, core concepts) +- high: 15% of use cases (common workflows, examples) +- medium: 4% of use cases (edge cases) +- low: 1% of use cases (rare scenarios) + +**Version**: `X.Y` (start 1.0, increment on changes) + +**Updated**: `YYYY-MM-DD` (ISO 8601, must match metadata section) + +--- + +## Examples + +```markdown + + + +``` + +--- + +## Validation + +- [ ] Frontmatter is first line? +- [ ] Format exact: ``? +- [ ] Priority is critical|high|medium|low? +- [ ] Version is X.Y? +- [ ] Date is YYYY-MM-DD? + +--- + +## Related + +- structure.md - File organization +- templates.md - File templates +- codebase-references.md - Linking to code diff --git a/.opencode/context/core/context-system/standards/templates.md b/.opencode/context/core/context-system/standards/templates.md index 4d7f202..8d432a0 100644 --- a/.opencode/context/core/context-system/standards/templates.md +++ b/.opencode/context/core/context-system/standards/templates.md @@ -22,6 +22,7 @@ ## 1. Concept Template ```markdown + # Concept: {Name} **Purpose**: [1 sentence] @@ -44,8 +45,22 @@ [<10 lines] ``` +## 📂 Codebase References + +**Business Logic** (if business domain): +- `path/to/rules.ts` - {3-10 word description} + +**Implementation**: +- `path/to/main.ts` - {3-10 word description} + +**Models/Types**: +- `path/to/model.ts` - {3-10 word description} + +**Tests**: +- `path/to/test.ts` - {3-10 word description} + ## Deep Dive -**Reference**: [Link] +**Reference**: [Link or "See implementation above"] ## Related - concepts/x.md @@ -57,6 +72,7 @@ ## 2. Example Template ```markdown + # Example: {What It Shows} **Purpose**: [1 sentence] @@ -79,6 +95,17 @@ - Detail 1 - Detail 2 +## 📂 Codebase References + +**Full Implementation**: +- `path/to/real-implementation.ts` - {Production version} + +**Related Code**: +- `path/to/helper.ts` - {Helper utilities} + +**Tests**: +- `path/to/test.ts` - {Tests demonstrating pattern} + ## Related - concepts/x.md ``` @@ -88,6 +115,7 @@ ## 3. Guide Template ```markdown + # Guide: {Action} **Purpose**: [1 sentence] @@ -106,6 +134,7 @@ {command} ``` **Expected**: [result] +**Implementation**: `path/to/step.ts` ### 2. {Step} [Repeat 4-7 steps] @@ -115,6 +144,20 @@ {verify command} ``` +## 📂 Codebase References + +**Workflow Orchestration**: +- `path/to/workflow.ts` - {Main workflow coordinator} + +**Business Logic** (if applicable): +- `path/to/rules.ts` - {Process validation rules} + +**Integration Points**: +- `path/to/api-client.ts` - {External integration} + +**Tests**: +- `path/to/workflow.test.ts` - {End-to-end tests} + ## Troubleshooting | Issue | Solution | |-------|----------| @@ -129,15 +172,16 @@ ## 4. Lookup Template ```markdown + # Lookup: {Reference Type} **Purpose**: Quick reference for {desc} **Last Updated**: {YYYY-MM-DD} ## {Section} -| Item | Value | Desc | -|------|-------|------| -| x | y | z | +| Item | Value | Desc | Code | +|------|-------|------|------| +| x | y | z | `path/to/file.ts` | ## Commands ```bash @@ -150,6 +194,17 @@ {path} - {desc} ``` +## 📂 Codebase References + +**Validation/Enforcement**: +- `path/to/validator.ts` - {Validation logic} + +**Configuration**: +- `path/to/config.ts` - {Configuration settings} + +**Tests**: +- `path/to/test.ts` - {Validation tests} + ## Related - concepts/x.md ``` @@ -159,6 +214,7 @@ ## 5. Error Template ```markdown + # Errors: {Framework} **Purpose**: Common errors for {framework} @@ -188,12 +244,30 @@ **Prevention**: [how to avoid] **Frequency**: common/occasional/rare -**Reference**: [link] + +**Code References**: +- Error thrown: `path/to/error-source.ts` +- Error handler: `path/to/error-handler.ts` +- Prevention: `path/to/validator.ts` --- [Repeat for 5-10 errors] +## 📂 Codebase References + +**Error Definitions**: +- `path/to/error-types.ts` - {Error class definitions} + +**Error Handling**: +- `path/to/error-handler.ts` - {Error handler} + +**Prevention Logic**: +- `path/to/validator.ts` - {Validation preventing errors} + +**Tests**: +- `path/to/error-handling.test.ts` - {Error handling tests} + ## Related - concepts/x.md ``` diff --git a/.opencode/context/core/visual-development.md b/.opencode/context/core/visual-development.md new file mode 100644 index 0000000..b25cf10 --- /dev/null +++ b/.opencode/context/core/visual-development.md @@ -0,0 +1,478 @@ + +# Visual Development Context + +**Purpose**: Visual content creation, UI design, image generation, and diagram creation + +--- + +## Quick Routes + +| Task Type | Context File | Subagent | Tools | +|-----------|-------------|----------|-------| +| **Generate image/diagram** | This file | Image Specialist | tool:gemini | +| **Edit existing image** | This file | Image Specialist | tool:gemini | +| **UI mockup (static)** | This file | Image Specialist | tool:gemini | +| **Interactive UI design** | `workflows/design-iteration.md` | - | - | +| **Design system** | `development/design-systems.md` | - | - | +| **UI standards** | `development/ui-styling-standards.md` | - | - | +| **Animation patterns** | `development/animation-patterns.md` | - | - | + +--- + +## Image Specialist Capabilities + +### What It Does + +The **Image Specialist** subagent uses Gemini Nano Banana AI to: + +- ✅ **Generate images from text descriptions** - Create original images, illustrations, graphics +- ✅ **Edit existing images** - Modify, enhance, or transform images +- ✅ **Analyze images** - Describe image content, extract information +- ✅ **Create diagrams** - Architecture diagrams, flowcharts, system visualizations +- ✅ **Design mockups** - UI mockups, wireframes, design concepts +- ✅ **Generate graphics** - Social media graphics, promotional images, icons + +### When to Delegate + +Delegate to Image Specialist when users request: + +**Keywords to Watch For**: +- "create image", "generate image", "make image" +- "diagram", "flowchart", "visualization" +- "mockup", "wireframe", "design concept" +- "graphic", "illustration", "icon" +- "edit image", "modify image", "enhance image" +- "screenshot", "visual", "picture" + +**Common Use Cases**: +1. **Architecture Diagrams** - Microservices, system design, infrastructure +2. **UI Mockups** - Dashboard designs, app interfaces, web layouts +3. **Social Media Graphics** - Announcements, promotions, branded content +4. **Documentation Images** - Tutorial screenshots, feature highlights, guides +5. **Presentations** - Slide graphics, charts, visual aids +6. **Marketing Assets** - Product images, hero graphics, banners + +### How to Invoke + +```javascript +task( + subagent_type="Image Specialist", + description="[Brief 3-5 word description]", + prompt="Context to load: + - .opencode/context/core/visual-development.md + + Task: [Detailed visual requirement] + + Requirements: + - Style: [Visual aesthetic - modern, minimalist, professional, etc.] + - Dimensions: [Width x Height or aspect ratio] + - Key Elements: [What must be included] + - Colors: [Color scheme, brand colors, palette] + - Format: [PNG, JPG, SVG preference] + + Output: [Expected deliverable and location]" +) +``` + +--- + +## Use Case Examples + +### 1. Architecture Diagram + +**User Request**: "Create a diagram showing our microservices architecture" + +**Invocation**: +```javascript +task( + subagent_type="Image Specialist", + description="Generate microservices architecture diagram", + prompt="Create a technical architecture diagram showing: + + **Services**: + - API Gateway (entry point) + - Auth Service (authentication) + - User Service (user management) + - Order Service (order processing) + - Payment Service (payment processing) + - Notification Service (emails/SMS) + + **Infrastructure**: + - PostgreSQL databases (one per service) + - Redis cache (shared) + - RabbitMQ message queue + - AWS S3 (file storage) + + **External Services**: + - Stripe (payments) + - SendGrid (emails) + - Twilio (SMS) + + **Style**: Clean, professional, modern tech diagram + **Colors**: Blue for services, green for databases, orange for external + **Format**: PNG, 1920x1080 + **Layout**: Left-to-right flow, clear connections + + Output: Save to docs/architecture-diagram.png" +) +``` + +--- + +### 2. UI Mockup + +**User Request**: "Show me what the dashboard could look like" + +**Invocation**: +```javascript +task( + subagent_type="Image Specialist", + description="Generate analytics dashboard mockup", + prompt="Create a UI mockup for an analytics dashboard: + + **Layout**: + - Top: Header with logo, navigation, user menu + - Below header: 4 metric cards in a row + * Total Users (with trend arrow) + * Revenue (with percentage change) + * Conversion Rate (with sparkline) + * Active Sessions (with live indicator) + - Middle: Large line chart showing 30-day trends + - Bottom: Data table with recent transactions + + **Style**: Modern, professional SaaS aesthetic + **Theme**: Dark mode with subtle gradients + **Colors**: + - Background: Dark gray (#1e293b) + - Cards: Slightly lighter (#334155) + - Accent: Blue (#3b82f6) + - Text: White/gray + **Typography**: Clean sans-serif (Inter-style) + **Format**: PNG, 1440x900 + + Output: Save to design_iterations/dashboard_mockup.png" +) +``` + +--- + +### 3. Social Media Graphic + +**User Request**: "Create a graphic announcing our new feature" + +**Invocation**: +```javascript +task( + subagent_type="Image Specialist", + description="Generate feature announcement graphic", + prompt="Create a social media graphic for feature launch: + + **Content**: + - Main headline: 'Introducing Real-Time Collaboration' + - Subheadline: 'Work together, ship faster' + - Small text: 'Available now for all teams' + + **Visual Elements**: + - Abstract illustration of people collaborating + - Subtle geometric shapes in background + - Modern, energetic feel + + **Brand Colors**: + - Primary: #6366f1 (indigo) + - Secondary: #8b5cf6 (purple) + - Background: White with gradient + - Text: Dark gray (#1e293b) + + **Format**: PNG, 1200x630 (optimized for Twitter/LinkedIn) + **Style**: Modern, professional, eye-catching + + Output: Save to marketing/feature-launch-social.png" +) +``` + +--- + +### 4. Flowchart/Process Diagram + +**User Request**: "Diagram the user onboarding flow" + +**Invocation**: +```javascript +task( + subagent_type="Image Specialist", + description="Generate user onboarding flowchart", + prompt="Create a flowchart showing user onboarding process: + + **Steps**: + 1. User signs up (email/password) + 2. Email verification sent + 3. User clicks verification link + 4. Profile setup (name, company, role) + 5. Choose plan (Free/Pro/Enterprise) + 6. Payment (if Pro/Enterprise) + 7. Onboarding tutorial (5 steps) + 8. Dashboard access + + **Decision Points**: + - Email verified? (Yes → Continue, No → Resend) + - Plan selected? (Free → Skip payment, Paid → Payment) + - Payment successful? (Yes → Continue, No → Retry) + + **Style**: Clean flowchart with standard symbols + **Colors**: + - Start/End: Green + - Process: Blue + - Decision: Yellow + - Error: Red + **Format**: PNG, 1600x1200 + **Layout**: Top-to-bottom flow + + Output: Save to docs/onboarding-flow.png" +) +``` + +--- + +### 5. Icon/Illustration + +**User Request**: "Create an icon for our file upload feature" + +**Invocation**: +```javascript +task( + subagent_type="Image Specialist", + description="Generate file upload icon", + prompt="Create a modern icon for file upload feature: + + **Concept**: Cloud with upward arrow + **Style**: + - Minimalist, clean lines + - Rounded corners + - Flat design (no gradients) + **Colors**: + - Primary: #3b82f6 (blue) + - Accent: #60a5fa (lighter blue) + **Size**: 512x512px (will be scaled down) + **Format**: PNG with transparent background + **Usage**: App UI, documentation, marketing + + Output: Save to assets/icons/upload-icon.png" +) +``` + +--- + +### 6. Image Editing + +**User Request**: "Make this screenshot look more professional" + +**Invocation**: +```javascript +task( + subagent_type="Image Specialist", + description="Enhance screenshot for documentation", + prompt="Edit the existing screenshot at docs/raw-screenshot.png: + + **Enhancements Needed**: + - Add subtle drop shadow for depth + - Round the corners (8px radius) + - Add a thin border (#e5e7eb) + - Increase contrast slightly + - Ensure text is crisp and readable + + **Optional**: + - Add subtle gradient background + - Highlight key UI elements with arrows/boxes + + **Output Format**: PNG, maintain original dimensions + **Quality**: High (for documentation) + + Output: Save to docs/enhanced-screenshot.png" +) +``` + +--- + +## Decision Tree: Image Specialist vs Design Iteration + +Use this decision tree to choose the right approach: + +``` +User needs visual content + ↓ +Is it interactive/responsive HTML/CSS? + ↓ + YES → Use design-iteration.md workflow + | - Create HTML files + | - Iterate on designs + | - Production-ready code + ↓ + NO → Is it a static visual asset? + ↓ + YES → Use Image Specialist + | - Diagrams + | - Mockups (non-interactive) + | - Graphics + | - Illustrations + ↓ + NO → Clarify requirements with user +``` + +### Quick Reference + +| Need | Use | +|------|-----| +| **Interactive dashboard** | design-iteration.md | +| **Dashboard mockup (static image)** | Image Specialist | +| **Responsive landing page** | design-iteration.md | +| **Landing page hero graphic** | Image Specialist | +| **Working HTML prototype** | design-iteration.md | +| **Architecture diagram** | Image Specialist | +| **UI component library** | design-iteration.md | +| **Social media graphic** | Image Specialist | + +--- + +## Tools & Dependencies + +### Required Tool + +**tool:gemini** - Gemini Nano Banana AI +- Automatically included in Developer profile +- Requires GEMINI_API_KEY environment variable +- Get API key: https://makersuite.google.com/app/apikey + +### Configuration + +Add to `.env` file: +```bash +GEMINI_API_KEY=your_api_key_here +``` + +### Capabilities + +- **Text-to-Image**: Generate images from descriptions +- **Image-to-Image**: Edit and transform existing images +- **Image Analysis**: Describe and analyze image content +- **Multiple Formats**: PNG, JPG, WebP support +- **High Resolution**: Up to 2048x2048 pixels + +--- + +## Best Practices + +### Writing Effective Prompts + +✅ **Do**: +- Be specific about dimensions and format +- Describe visual style clearly (modern, minimalist, professional) +- Specify colors using hex codes or names +- Include key elements that must appear +- Mention the intended use case +- Provide context about brand/aesthetic + +❌ **Don't**: +- Use vague descriptions ("make it nice") +- Forget to specify dimensions +- Assume default style preferences +- Skip color specifications +- Omit output location + +### Example: Good vs Bad Prompts + +**❌ Bad Prompt**: +``` +"Create a diagram of our system" +``` + +**✅ Good Prompt**: +``` +"Create a technical architecture diagram showing: +- 3 microservices (API, Auth, Database) +- AWS infrastructure (EC2, RDS, S3) +- External APIs (Stripe, SendGrid) + +Style: Clean, professional, modern +Colors: Blue for services, green for databases +Format: PNG, 1920x1080 +Layout: Left-to-right flow with clear connections + +Output: docs/system-architecture.png" +``` + +--- + +## Quality Checklist + +Before delegating to Image Specialist: + +- [ ] User request clearly indicates need for visual content +- [ ] Determined static image is appropriate (not interactive HTML) +- [ ] Gathered requirements: style, dimensions, colors, elements +- [ ] Specified output format and location +- [ ] Confirmed tool:gemini is available in profile +- [ ] Prepared detailed prompt with all specifications + +After receiving output: + +- [ ] Image meets specified requirements +- [ ] Dimensions and format are correct +- [ ] Visual style matches request +- [ ] All key elements are included +- [ ] Image is saved to specified location +- [ ] User is satisfied with result + +--- + +## Troubleshooting + +### Common Issues + +**Issue**: Generated image doesn't match expectations +**Solution**: Refine prompt with more specific details, provide reference examples + +**Issue**: Image quality is low +**Solution**: Request higher resolution, specify quality requirements in prompt + +**Issue**: Colors don't match brand +**Solution**: Provide exact hex codes, reference brand guidelines + +**Issue**: Layout is cluttered +**Solution**: Simplify requirements, specify clear hierarchy and spacing + +**Issue**: Text in image is unreadable +**Solution**: Request larger text, higher contrast, clearer typography + +--- + +## Related Context + +- **UI Design Workflow**: `.opencode/context/core/workflows/design-iteration.md` +- **Design Systems**: `.opencode/context/development/design-systems.md` +- **UI Styling Standards**: `.opencode/context/development/ui-styling-standards.md` +- **Animation Patterns**: `.opencode/context/development/animation-patterns.md` +- **Subagent Invocation Guide**: `.opencode/context/openagents-repo/guides/subagent-invocation.md` +- **Agent Capabilities**: `.opencode/context/openagents-repo/core-concepts/agents.md` + +--- + +## Keywords for Discovery + +**ContextScout should find this file when users mention**: + +- image, images, picture, photo, graphic +- diagram, flowchart, visualization, chart +- mockup, wireframe, design, concept +- illustration, icon, asset, visual +- generate, create, make, design +- screenshot, capture, render +- architecture, system, flow, process +- social media, marketing, promotional +- edit, modify, enhance, transform +- UI, interface, dashboard, layout + +--- + +## Version History + +- **v1.0** (2025-01-27): Initial creation with comprehensive use cases and examples diff --git a/.opencode/context/core/workflows/design-iteration.md b/.opencode/context/core/workflows/design-iteration.md index c2bea8d..c7b2e2b 100644 --- a/.opencode/context/core/workflows/design-iteration.md +++ b/.opencode/context/core/workflows/design-iteration.md @@ -319,6 +319,108 @@ design_iterations/ --- +## Visual Content Generation + +### When to Use Image Specialist + +Delegate to **Image Specialist** subagent when users request: + +- **Diagrams & Visualizations**: Architecture diagrams, flowcharts, system visualizations +- **UI Mockups & Wireframes**: Visual mockups, design concepts, interface previews +- **Graphics & Assets**: Social media graphics, promotional images, icons, illustrations +- **Image Editing**: Photo enhancement, image modifications, visual adjustments + +### Invocation Pattern + +```javascript +task( + subagent_type="Image Specialist", + description="Generate/edit visual content", + prompt="Context to load: + - .opencode/context/core/visual-development.md + + Task: [Specific visual requirement] + + Requirements: + - [Visual style/aesthetic] + - [Dimensions/format] + - [Key elements to include] + - [Color scheme/branding] + + Output: [Expected deliverable]" +) +``` + +### Example Use Cases + +**Architecture Diagram**: +```javascript +task( + subagent_type="Image Specialist", + description="Generate microservices architecture diagram", + prompt="Create a diagram showing: + - 5 microservices (API Gateway, Auth, Orders, Payments, Notifications) + - Database connections + - Message queue (RabbitMQ) + - External services (Stripe, SendGrid) + + Style: Clean, professional, modern + Format: PNG, 1920x1080" +) +``` + +**UI Mockup**: +```javascript +task( + subagent_type="Image Specialist", + description="Generate dashboard mockup", + prompt="Create a mockup for an analytics dashboard: + - Header with navigation + - 4 metric cards (Users, Revenue, Conversion, Retention) + - Line chart showing trends + - Data table below + + Style: Modern, dark theme, professional + Format: PNG, 1440x900" +) +``` + +**Social Media Graphic**: +```javascript +task( + subagent_type="Image Specialist", + description="Generate product launch graphic", + prompt="Create a social media graphic announcing new feature: + - Bold headline: 'Introducing Real-Time Collaboration' + - Subtext: 'Work together, ship faster' + - Brand colors: #6366f1 (primary), #1e293b (dark) + - Include abstract collaboration visual + + Format: PNG, 1200x630 (Twitter/LinkedIn)" +) +``` + +### Tools Required + +- **tool:gemini** - Gemini Nano Banana AI for image generation/editing +- Automatically available in Developer profile + +### When NOT to Delegate + +**Use design-iteration workflow instead** when: +- Creating interactive HTML/CSS designs +- Building complete UI implementations +- Iterating on existing HTML files +- Need responsive, production-ready code + +**Use image-specialist** when: +- Need static visual assets +- Creating diagrams or illustrations +- Generating mockups for presentation +- Quick visual concepts without code + +--- + ## Iteration Process ### When to Create Iterations diff --git a/.opencode/profiles/advanced/profile.json b/.opencode/profiles/advanced/profile.json index 7e6b6e2..63e19b0 100644 --- a/.opencode/profiles/advanced/profile.json +++ b/.opencode/profiles/advanced/profile.json @@ -41,9 +41,6 @@ "command:validate-repo", "tool:env", "tool:gemini", - "plugin:notify", - "plugin:telegram-bot", - "plugin:telegram-notify", "context:essential-patterns", "context:project-context", "context:quick-start", diff --git a/.opencode/profiles/business/profile.json b/.opencode/profiles/business/profile.json index d539264..8df5285 100644 --- a/.opencode/profiles/business/profile.json +++ b/.opencode/profiles/business/profile.json @@ -16,9 +16,6 @@ "command:prompt-enhancer", "tool:env", "tool:gemini", - "plugin:notify", - "plugin:telegram-bot", - "plugin:telegram-notify", "context:essential-patterns", "context:project-context", "context:quick-start", diff --git a/.opencode/profiles/developer/profile.json b/.opencode/profiles/developer/profile.json index 8fc5a68..74c77a1 100644 --- a/.opencode/profiles/developer/profile.json +++ b/.opencode/profiles/developer/profile.json @@ -17,6 +17,7 @@ "subagent:build-agent", "subagent:codebase-pattern-analyst", "subagent:contextscout", + "subagent:image-specialist", "skill:task-management", "command:commit", "command:test", @@ -25,6 +26,7 @@ "command:optimize", "command:validate-repo", "tool:env", + "tool:gemini", "context:essential-patterns", "context:project-context", "context:quick-start", @@ -32,6 +34,10 @@ "context:project-intelligence/*", "context:to-be-consumed/*", "context:adding-skill", + "context:development/ui-styling-standards", + "context:development/design-systems", + "context:development/design-assets", + "context:development/animation-patterns", "config:env-example", "config:readme" ] diff --git a/.opencode/profiles/full/profile.json b/.opencode/profiles/full/profile.json index 5d871f4..ff6b9a4 100644 --- a/.opencode/profiles/full/profile.json +++ b/.opencode/profiles/full/profile.json @@ -32,9 +32,6 @@ "command:validate-repo", "tool:env", "tool:gemini", - "plugin:notify", - "plugin:telegram-bot", - "plugin:telegram-notify", "context:essential-patterns", "context:project-context", "context:quick-start", diff --git a/.opencode/skill/context7/SKILLS.MD b/.opencode/skill/context7/SKILLS.MD new file mode 100644 index 0000000..76160b2 --- /dev/null +++ b/.opencode/skill/context7/SKILLS.MD @@ -0,0 +1,85 @@ +--- +name: context7 +description: Retrieve up-to-date documentation for software libraries, frameworks, and components via the Context7 API. This skill should be used when looking up documentation for any programming library or framework, finding code examples for specific APIs or features, verifying correct usage of library functions, or obtaining current information about library APIs that may have changed since training. +--- + +# Context7 + +## Overview + +This skill enables retrieval of current documentation for software libraries and components by querying the Context7 API via curl. Use it instead of relying on potentially outdated training data. + +## Workflow + +### Step 1: Search for the Library + +To find the Context7 library ID, query the search endpoint: + +```bash +curl -s "https://context7.com/api/v2/libs/search?libraryName=LIBRARY_NAME&query=TOPIC" | jq '.results[0]' +``` + +**Parameters:** +- `libraryName` (required): The library name to search for (e.g., "react", "nextjs", "fastapi", "axios") +- `query` (required): A description of the topic for relevance ranking + +**Response fields:** +- `id`: Library identifier for the context endpoint (e.g., `/websites/react_dev_reference`) +- `title`: Human-readable library name +- `description`: Brief description of the library +- `totalSnippets`: Number of documentation snippets available + +### Step 2: Fetch Documentation + +To retrieve documentation, use the library ID from step 1: + +```bash +curl -s "https://context7.com/api/v2/context?libraryId=LIBRARY_ID&query=TOPIC&type=txt" +``` + +**Parameters:** +- `libraryId` (required): The library ID from search results +- `query` (required): The specific topic to retrieve documentation for +- `type` (optional): Response format - `json` (default) or `txt` (plain text, more readable) + +## Examples + +### React hooks documentation + +```bash +# Find React library ID +curl -s "https://context7.com/api/v2/libs/search?libraryName=react&query=hooks" | jq '.results[0].id' +# Returns: "/websites/react_dev_reference" + +# Fetch useState documentation +curl -s "https://context7.com/api/v2/context?libraryId=/websites/react_dev_reference&query=useState&type=txt" +``` + +### Next.js routing documentation + +```bash +# Find Next.js library ID +curl -s "https://context7.com/api/v2/libs/search?libraryName=nextjs&query=routing" | jq '.results[0].id' + +# Fetch app router documentation +curl -s "https://context7.com/api/v2/context?libraryId=/vercel/next.js&query=app+router&type=txt" +``` + +### FastAPI dependency injection + +```bash +# Find FastAPI library ID +curl -s "https://context7.com/api/v2/libs/search?libraryName=fastapi&query=dependencies" | jq '.results[0].id' + +# Fetch dependency injection documentation +curl -s "https://context7.com/api/v2/context?libraryId=/fastapi/fastapi&query=dependency+injection&type=txt" +``` + +## Tips + +- Use `type=txt` for more readable output +- Use `jq` to filter and format JSON responses +- Be specific with the `query` parameter to improve relevance ranking +- If the first search result is not correct, check additional results in the array +- URL-encode query parameters containing spaces (use `+` or `%20`) +- No API key is required for basic usage (rate-limited) \ No newline at end of file diff --git a/README.md b/README.md index c0ab8d9..64c7522 100644 --- a/README.md +++ b/README.md @@ -106,19 +106,19 @@ The installer offers: macOS / Linux / Git Bash / WSL ```bash -# Essential - Minimal essentials (9 components) +# Essential - Minimal essentials (23 components) curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s essential -# Developer - Recommended for daily work (19 components) +# Developer - Recommended for daily work (37 components) curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s developer -# Business - Business automation and content creation (15 components) +# Business - Business automation and content creation (23 components) curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s business -# Full - Everything included (25 components) +# Full - Everything included (39 components) curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s full -# Advanced - Full + System Builder (32 components) +# Advanced - Full + System Builder (48 components) curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s advanced ``` @@ -520,7 +520,7 @@ curl -o ~/.opencode/agent/core/opencoder.md \ The installer offers five pre-configured profiles: -### 🎯 Essential (Minimal - 9 components) +### 🎯 Essential (Minimal - 23 components) Minimal starter kit - universal agent with core subagents. - **Agents**: openagent - **Subagents**: task-manager, documentation @@ -530,34 +530,34 @@ Minimal starter kit - universal agent with core subagents. - **Config**: env-example - **Best for**: Learning the system, lightweight tasks, minimal setup -### 💼 Developer (Recommended - 30 components) -Complete software development environment with code generation, testing, review, and build tools. +### 💼 Developer (Recommended - 37 components) +Complete software development environment with code generation, testing, review, build tools, and visual content creation. - Everything in Essential, plus: -- **Agents**: opencoder -- **Subagents**: coder-agent, reviewer, tester, build-agent, codebase-pattern-analyst +- **Agents**: opencoder, frontend-specialist, backend-specialist, devops-specialist, codebase-agent +- **Subagents**: coder-agent, reviewer, tester, build-agent, codebase-pattern-analyst, image-specialist - **Commands**: commit, test, optimize, validate-repo -- **Context**: All standards and workflow files (code, patterns, tests, docs, analysis, delegation, sessions, task-breakdown, review, context-guide) +- **Tools**: gemini (AI image generation) +- **Context**: All core standards and workflows, plus visual development (UI styling, design systems, design assets, animation patterns) - **Config**: readme -- **Best for**: Most developers, daily use, full-featured development +- **Best for**: Most developers, daily use, full-featured development with visual content creation -### 📊 Business (15 components) +### 📊 Business (23 components) Business process automation, content creation, and visual workflows. -- **Agents**: openagent +- **Agents**: openagent, copywriter, technical-writer, data-analyst - **Subagents**: task-manager, documentation, image-specialist - **Commands**: context, clean, prompt-enhancer - **Tools**: env, gemini (AI image generation) -- **Plugins**: notify, telegram-notify -- **Context**: essential-patterns, project-context +- **Context**: essential-patterns, project-context, and all core standards - **Config**: env-example, readme - **Best for**: Business automation, content creation, non-developers -### 📦 Full (36 components) -Everything included - all agents, subagents, tools, and plugins. +### 📦 Full (39 components) +Everything included - all agents, subagents, and tools for maximum functionality. - Everything in Developer and Business combined, plus: - **Commands**: worktrees (git worktree management), validate-repo - **Best for**: Power users, exploring all features -### 🚀 Advanced (43 components) +### 🚀 Advanced (48 components) Full installation plus **System Builder** for creating custom AI architectures. - Everything in Full, plus: - **Agents**: system-builder diff --git a/WORKFLOW_GUIDE.md b/WORKFLOW_GUIDE.md deleted file mode 100644 index 2826f73..0000000 --- a/WORKFLOW_GUIDE.md +++ /dev/null @@ -1,327 +0,0 @@ -# CI/CD Workflow Guide - Build Validation System - -## Overview - -The build validation system has **two workflows** that handle different scenarios: - -1. **PR Workflow** - Validates and blocks merge if registry is invalid -2. **Direct Push Workflow** - Auto-updates registry on direct pushes to main - ---- - -## Workflow 1: Pull Request Validation - -**File:** `.github/workflows/validate-registry.yml` - -**Triggers:** -- Pull requests to `main` or `dev` branches -- Changes to `.opencode/**`, `registry.json`, or validation scripts - -**What It Does:** - -``` -Developer creates PR - ↓ -GitHub Action runs automatically - ↓ -1. Auto-detect new components - - Scans .opencode/ directory - - Finds files not in registry - ↓ -2. Add to registry (if found) - - Extracts metadata - - Adds to registry.json - - Commits to PR branch - ↓ -3. Validate registry - - Checks all paths exist - - Verifies JSON is valid - ↓ -4. Decision - ├─ ✅ Valid → PR can merge - └─ ❌ Invalid → PR BLOCKED -``` - -**Key Features:** -- ✅ **Blocks merge** if validation fails -- ✅ **Auto-commits** registry updates to PR branch -- ✅ **Detailed feedback** in PR checks -- ✅ **Prevents 404 errors** before they reach main - -**Example Output:** -``` -🔍 Auto-Detection Results -⚠️ New command: my-new-command - Path: .opencode/command/my-new-command.md - -📝 Adding New Components -✓ Added command: my-new-command - -✅ Registry Validation -All registry paths are valid! -Total paths: 51 -Valid: 51 -Missing: 0 - -✅ Validation Passed -This PR is ready for review! -``` - ---- - -## Workflow 2: Direct Push to Main - -**File:** `.github/workflows/update-registry.yml` - -**Triggers:** -- Direct pushes to `main` branch -- Changes to `.opencode/**` (excluding registry.json) -- Manual workflow dispatch - -**What It Does:** - -``` -Developer pushes directly to main - ↓ -GitHub Action runs automatically - ↓ -1. Auto-detect new components - - Scans .opencode/ directory - - Finds files not in registry - ↓ -2. Add to registry (if found) - - Extracts metadata - - Adds to registry.json - - Commits to main - ↓ -3. Validate registry - - Checks all paths exist - - Verifies JSON is valid - ↓ -4. Report results - ├─ ✅ Valid → Success - └─ ⚠️ Invalid → Warning (doesn't block) -``` - -**Key Differences from PR Workflow:** -- ⚠️ **Does NOT block** - push already happened -- ⚠️ **Shows warning** if validation fails -- ✅ **Auto-commits** registry updates -- ✅ **Validates** but doesn't prevent push - -**Why No Blocking?** -Since the push already happened, we can't block it. Instead: -- Shows clear warning in Actions summary -- Alerts team to fix registry -- Prevents future installation errors - -**Example Output:** -``` -🔍 Auto-Detection Results -✅ No new components found - -✅ Registry Validation -All registry paths are valid! - -Registry Statistics -- Agents: 4 -- Commands: 12 -- Contexts: 15 -``` - ---- - -## Comparison Table - -| Feature | PR Workflow | Direct Push Workflow | -|---------|-------------|---------------------| -| **Triggers** | Pull requests | Direct push to main | -| **Auto-detect** | ✅ Yes | ✅ Yes | -| **Auto-add** | ✅ Yes | ✅ Yes | -| **Validate** | ✅ Yes | ✅ Yes | -| **Block on failure** | ✅ Yes | ❌ No (warns only) | -| **Auto-commit** | ✅ To PR branch | ✅ To main | -| **Use case** | Normal development | Emergency fixes, maintainers | - ---- - -## Recommended Workflow - -### For Contributors (Recommended) - -```bash -# 1. Create feature branch -git checkout -b feature/my-new-component - -# 2. Add your component -echo "--- -description: My awesome component ---- -# My Component" > .opencode/command/my-component.md - -# 3. Commit and push -git add .opencode/command/my-component.md -git commit -m "feat: add my-component" -git push origin feature/my-new-component - -# 4. Create PR to dev -gh pr create --base dev --title "Add my-component" - -# 5. GitHub Actions will: -# - Auto-detect your component -# - Add to registry.json -# - Validate all paths -# - Commit to your PR branch -# - Block merge if invalid - -# 6. Review and merge -# Your component is now in registry! -``` - -### For Maintainers (Direct Push) - -```bash -# 1. Add component directly to main -git checkout main -echo "--- -description: Urgent fix ---- -# Fix" > .opencode/command/urgent-fix.md - -# 2. Commit and push -git add .opencode/command/urgent-fix.md -git commit -m "fix: urgent component" -git push origin main - -# 3. GitHub Actions will: -# - Auto-detect your component -# - Add to registry.json -# - Validate all paths -# - Commit registry update to main -# - Warn if validation fails (but doesn't block) - -# 4. Check Actions tab for results -# If warning, fix registry and push correction -``` - ---- - -## Manual Validation (Local) - -Before pushing, you can validate locally: - -```bash -# Check for new components -./scripts/auto-detect-components.sh --dry-run - -# Add new components -./scripts/auto-detect-components.sh --auto-add - -# Validate registry -./scripts/validate-registry.sh -v - -# Get fix suggestions -./scripts/validate-registry.sh --fix -``` - ---- - -## Troubleshooting - -### PR Blocked - Validation Failed - -**Problem:** PR shows validation failure - -**Solution:** -```bash -# 1. Check the error in PR checks -# 2. Run validator locally -./scripts/validate-registry.sh --fix - -# 3. Fix the issues (usually path typos) -# 4. Commit and push -git add registry.json -git commit -m "fix: correct registry paths" -git push - -# 5. PR checks will re-run automatically -``` - -### Direct Push - Validation Warning - -**Problem:** Push succeeded but Actions shows warning - -**Solution:** -```bash -# 1. Check Actions tab for details -# 2. Run validator locally -./scripts/validate-registry.sh --fix - -# 3. Fix registry.json -# 4. Push correction -git add registry.json -git commit -m "fix: correct registry after direct push" -git push origin main -``` - -### Component Not Auto-Detected - -**Problem:** Added file but not detected - -**Possible causes:** -- File in excluded directory (tests/, docs/, node_modules/) -- File is README.md or index.md (excluded) -- File doesn't have .md extension -- File in wrong location (not in .opencode/) - -**Solution:** -```bash -# Check if file would be detected -./scripts/auto-detect-components.sh --dry-run - -# If not detected, check file location and name -# Move to correct location: -# - Agents: .opencode/agent/ -# - Commands: .opencode/command/ -# - Tools: .opencode/tool/ -# - Plugins: .opencode/plugin/ -# - Contexts: .opencode/context/ -``` - ---- - -## Best Practices - -### ✅ DO - -- **Use PRs** for normal development (recommended) -- **Add frontmatter** to components with description -- **Test locally** before pushing -- **Review auto-commits** in PR before merging -- **Keep registry.json** in sync with files - -### ❌ DON'T - -- **Don't bypass PRs** unless emergency -- **Don't manually edit** registry.json (let automation handle it) -- **Don't ignore** validation warnings -- **Don't commit** broken registry paths -- **Don't skip** local validation - ---- - -## Summary - -**For 99% of cases:** Use PR workflow -- Creates PR → Auto-detect → Validate → Block if invalid → Merge - -**For emergencies:** Direct push works -- Push to main → Auto-detect → Validate → Warn if invalid - -**Both workflows:** -- ✅ Auto-detect new components -- ✅ Update registry automatically -- ✅ Validate all paths -- ✅ Prevent installation 404 errors - -**The system ensures registry accuracy whether you use PRs or direct pushes!** diff --git a/registry.json b/registry.json index cd1cd0c..c6f664e 100644 --- a/registry.json +++ b/registry.json @@ -333,17 +333,7 @@ "knowledge-management" ], "dependencies": [ - "context:harvest", - "context:extract", - "context:organize", - "context:update", - "context:error", - "context:mvi", - "context:structure", - "context:templates", - "context:workflows", - "context:compact", - "context:creation" + "context:core/context-system/*" ], "category": "meta" }, @@ -1384,6 +1374,37 @@ "dependencies": [], "category": "standard" }, + { + "id": "frontmatter", + "name": "Frontmatter Standard", + "type": "context", + "path": ".opencode/context/core/context-system/standards/frontmatter.md", + "description": "HTML comment frontmatter format for all context files", + "tags": [ + "context-system", + "standards", + "frontmatter", + "metadata" + ], + "dependencies": [], + "category": "standard" + }, + { + "id": "codebase-references", + "name": "Codebase References Standard", + "type": "context", + "path": ".opencode/context/core/context-system/standards/codebase-references.md", + "description": "How to link context files to actual code implementation", + "tags": [ + "context-system", + "standards", + "codebase", + "references", + "documentation" + ], + "dependencies": [], + "category": "standard" + }, { "id": "navigation", "name": "Navigation", diff --git a/scripts/registry/validate-registry.sh b/scripts/registry/validate-registry.sh index 610877f..80606ce 100755 --- a/scripts/registry/validate-registry.sh +++ b/scripts/registry/validate-registry.sh @@ -312,13 +312,28 @@ check_dependency_exists() { # For context dependencies, also try path-based lookup # Format: context:core/standards/code -> .opencode/context/core/standards/code.md if [ "$dep_type" = "context" ]; then - local context_path=".opencode/context/${dep_id}.md" - local exists_by_path - exists_by_path=$(jq -r ".components.${registry_category}[]? | select(.path == \"${context_path}\") | .id" "$REGISTRY_FILE" 2>/dev/null) - - if [ -n "$exists_by_path" ]; then - echo "found" - return 0 + # Check for wildcard pattern (e.g., context:core/context-system/*) + if [[ "$dep_id" == *"*" ]]; then + # Extract prefix before wildcard + local prefix="${dep_id%%\**}" + # Check if any context files match the prefix + local matches + matches=$(jq -r ".components.${registry_category}[]? | select(.path | startswith(\".opencode/context/${prefix}\")) | .id" "$REGISTRY_FILE" 2>/dev/null | head -1) + + if [ -n "$matches" ]; then + echo "found" + return 0 + fi + else + # Try exact path match + local context_path=".opencode/context/${dep_id}.md" + local exists_by_path + exists_by_path=$(jq -r ".components.${registry_category}[]? | select(.path == \"${context_path}\") | .id" "$REGISTRY_FILE" 2>/dev/null) + + if [ -n "$exists_by_path" ]; then + echo "found" + return 0 + fi fi fi