create-universal-ai-context 2.5.0 → 2.6.0-final

package/templates/base/context/workflows/WORKFLOW_TEMPLATE.md

@@ -1,294 +1,294 @@
-# [Workflow Name] Workflow
-
-**Last Updated:** YYYY-MM-DD
-**Last Verified Against Code:** YYYY-MM-DD (commit: HASH)
-**Complexity:** HIGH / MEDIUM / LOW
-**Token Estimate:** ~XX,XXX tokens (X% of 200k context)
-
----
-
-## Quick Navigation
-
-- [Overview](#overview)
-- [Entry Points](#entry-points)
-- [Sub-Workflow 1: [Name]](#sub-workflow-1-name)
-- [Sub-Workflow 2: [Name]](#sub-workflow-2-name)
-- [Database Schema](#database-schema)
-- [External APIs](#external-apis)
-- [Test Coverage](#test-coverage)
-- [Known Gotchas](#known-gotchas)
-- [Complete Call Chain](#complete-call-chain)
-- [File Reference Table](#file-reference-table)
-
----
-
-## Overview
-
-**User Journey:**
-[Describe what the user experiences from start to finish]
-
-**Key Features:**
-- [Feature 1]
-- [Feature 2]
-- [Feature 3]
-
-**Business Logic Summary:**
-[2-3 sentences explaining the core business rules]
-
----
-
-## Entry Points
-
-### Entry Point 1: [Name]
-
-**File:** `path/to/file.ext` [Line XXX]
-**Function:** `function_name()` [Lines XXX-YYY]
-**Trigger:** [What triggers this entry point - API call, button click, scheduled job, etc.]
-
-```
-[Brief code snippet if helpful]
-```
-
----
-
-### Entry Point 2: [Name]
-
-[Same structure as Entry Point 1...]
-
----
-
-## Sub-Workflow 1: [Name]
-
-**Purpose:** [What this sub-workflow accomplishes]
-**Entry Point:** `file.ext:function_name()` [Line XXX]
-
-### Call Chain
-
-```
-function_name() [file.ext:XXX]
-├─ step_one() [file.ext:YYY]
-│  ├─ helper_a() [helper.ext:ZZZ]
-│  └─ helper_b() [helper.ext:AAA]
-├─ step_two() [file.ext:BBB]
-│  └─ database_query() [crud.ext:CCC]
-└─ step_three() [file.ext:DDD]
-   └─ external_api() [client.ext:EEE]
-```
-
-### Database Operations
-
-| Operation | Table | Purpose |
-|-----------|-------|---------|
-| READ | `table_name` | [Why reading] |
-| WRITE | `table_name` | [What writing] |
-| UPDATE | `table_name` | [What updating] |
-
-### External APIs
-
-| API | Endpoint | Purpose |
-|-----|----------|---------|
-| [API Name] | `POST /endpoint` | [What it does] |
-
-### Error Handling
-
-| Error | Handling | Recovery |
-|-------|----------|----------|
-| [Error type] | [How handled] | [How to recover] |
-
----
-
-## Sub-Workflow 2: [Name]
-
-[Same structure as Sub-Workflow 1...]
-
----
-
-## Database Schema
-
-### Tables Involved
-
-| Table | Purpose | Key Fields |
-|-------|---------|------------|
-| `table_1` | [Purpose] | `field_a`, `field_b` |
-| `table_2` | [Purpose] | `field_c`, `field_d` |
-
-### Relationships
-
-```
-table_1 ─┬─< table_2 (one-to-many via foreign_key)
-         └─< table_3 (one-to-many via other_key)
-```
-
-### Schema Notes
-
-[Any important schema considerations, constraints, indexes, etc.]
-
----
-
-## External APIs
-
-### [API Name 1]
-
-**Base URL:** `https://api.example.com`
-**Authentication:** [Method - API Key, OAuth, etc.]
-**Rate Limits:** [If applicable]
-
-**Endpoints Used:**
-| Endpoint | Method | Purpose |
-|----------|--------|---------|
-| `/endpoint` | POST | [What it does] |
-
-**Error Codes:**
-| Code | Meaning | Handling |
-|------|---------|----------|
-| 400 | [Meaning] | [How handled] |
-| 500 | [Meaning] | [How handled] |
-
----
-
-## Test Coverage
-
-### E2E Tests
-
-| Test File | Test Name | Coverage |
-|-----------|-----------|----------|
-| `tests/e2e/test_file.ext` | `test_scenario` | Sub-workflows 1-3 |
-
-### Unit Tests
-
-| Test File | Coverage Area |
-|-----------|---------------|
-| `tests/unit/test_file.ext` | Function X, Function Y |
-
-### Coverage Gaps
-
-- ❌ [Missing test scenario 1]
-- ❌ [Missing test scenario 2]
-- ⚠️ [Edge case not covered]
-
-### Running Tests
-
-```bash
-# Run all tests for this workflow
-[test command]
-
-# Run specific test
-[specific test command]
-```
-
----
-
-## Known Gotchas
-
-### Gotcha 1: [Title]
-
-**Severity:** CRITICAL / HIGH / MEDIUM / LOW
-**Symptom:** [What goes wrong]
-**Root Cause:** [Why it happens]
-
-**Fix:**
-```
-[Code or steps to fix]
-```
-
-**Prevention:**
-- [How to avoid in future]
-
-**Workflow Impact:** Sub-Workflow [X] is affected
-
----
-
-### Gotcha 2: [Title]
-
-[Same structure as Gotcha 1...]
-
----
-
-## Complete Call Chain
-
-### End-to-End Flow Diagram
-
-```
-[User Action / Trigger]
-         │
-         ▼
-┌─────────────────────┐
-│   Entry Point       │ file.ext:XXX
-│   function_name()   │
-└─────────┬───────────┘
-          │
-          ▼
-┌─────────────────────┐
-│   Sub-Workflow 1    │
-│   [Name]            │
-└─────────┬───────────┘
-          │
-          ▼
-┌─────────────────────┐
-│   Sub-Workflow 2    │ ──► [External API]
-│   [Name]            │
-└─────────┬───────────┘
-          │
-          ▼
-┌─────────────────────┐
-│   Database          │
-│   Operations        │
-└─────────┬───────────┘
-          │
-          ▼
-┌─────────────────────┐
-│   Response/         │
-│   Completion        │
-└─────────────────────┘
-```
-
-### State Transitions (if applicable)
-
-```
-[STATE_A] ──event──► [STATE_B] ──event──► [STATE_C]
-     │                                        │
-     └──────────── error ────────────────────►│
-                                              ▼
-                                         [STATE_ERROR]
-```
-
----
-
-## File Reference Table
-
-| File | Size | Purpose | Key Functions |
-|------|------|---------|---------------|
-| `path/file_1.ext` | XX KB | [What it does] | `func_a:XXX`, `func_b:YYY` |
-| `path/file_2.ext` | XX KB | [What it does] | `func_c:ZZZ` |
-| `path/file_3.ext` | XX KB | [What it does] | `func_d:AAA` |
-
----
-
-## Maintenance Schedule
-
-| Task | Frequency | Last Done | Next Due |
-|------|-----------|-----------|----------|
-| Verify line numbers | Monthly | YYYY-MM-DD | YYYY-MM-DD |
-| Full audit | Quarterly | YYYY-MM-DD | YYYY-MM-DD |
-
----
-
-## Related Documentation
-
-- **Parent Index:** [WORKFLOW_INDEX.md](../WORKFLOW_INDEX.md)
-- **Related Workflows:** [workflow_2.md](./workflow_2.md)
-- **Responsible Agent:** [agent-name.md](../../agents/agent-name.md)
-
----
-
-## Change Log
-
-| Date | Change | Commit |
-|------|--------|--------|
-| YYYY-MM-DD | Initial documentation | `hash` |
-
----
-
-**Version:** 1.0
-**Word Count:** ~XXX words
-**Token Estimate:** ~XX,XXX tokens
+# [Workflow Name] Workflow
+
+**Last Updated:** YYYY-MM-DD
+**Last Verified Against Code:** YYYY-MM-DD (commit: HASH)
+**Complexity:** HIGH / MEDIUM / LOW
+**Token Estimate:** ~XX,XXX tokens (X% of 200k context)
+
+---
+
+## Quick Navigation
+
+- [Overview](#overview)
+- [Entry Points](#entry-points)
+- [Sub-Workflow 1: [Name]](#sub-workflow-1-name)
+- [Sub-Workflow 2: [Name]](#sub-workflow-2-name)
+- [Database Schema](#database-schema)
+- [External APIs](#external-apis)
+- [Test Coverage](#test-coverage)
+- [Known Gotchas](#known-gotchas)
+- [Complete Call Chain](#complete-call-chain)
+- [File Reference Table](#file-reference-table)
+
+---
+
+## Overview
+
+**User Journey:**
+[Describe what the user experiences from start to finish]
+
+**Key Features:**
+- [Feature 1]
+- [Feature 2]
+- [Feature 3]
+
+**Business Logic Summary:**
+[2-3 sentences explaining the core business rules]
+
+---
+
+## Entry Points
+
+### Entry Point 1: [Name]
+
+**File:** `path/to/file.ext` [Line XXX]
+**Function:** `function_name()` [Lines XXX-YYY]
+**Trigger:** [What triggers this entry point - API call, button click, scheduled job, etc.]
+
+```
+[Brief code snippet if helpful]
+```
+
+---
+
+### Entry Point 2: [Name]
+
+[Same structure as Entry Point 1...]
+
+---
+
+## Sub-Workflow 1: [Name]
+
+**Purpose:** [What this sub-workflow accomplishes]
+**Entry Point:** `file.ext:function_name()` [Line XXX]
+
+### Call Chain
+
+```
+function_name() [file.ext:XXX]
+├─ step_one() [file.ext:YYY]
+│  ├─ helper_a() [helper.ext:ZZZ]
+│  └─ helper_b() [helper.ext:AAA]
+├─ step_two() [file.ext:BBB]
+│  └─ database_query() [crud.ext:CCC]
+└─ step_three() [file.ext:DDD]
+   └─ external_api() [client.ext:EEE]
+```
+
+### Database Operations
+
+| Operation | Table | Purpose |
+|-----------|-------|---------|
+| READ | `table_name` | [Why reading] |
+| WRITE | `table_name` | [What writing] |
+| UPDATE | `table_name` | [What updating] |
+
+### External APIs
+
+| API | Endpoint | Purpose |
+|-----|----------|---------|
+| [API Name] | `POST /endpoint` | [What it does] |
+
+### Error Handling
+
+| Error | Handling | Recovery |
+|-------|----------|----------|
+| [Error type] | [How handled] | [How to recover] |
+
+---
+
+## Sub-Workflow 2: [Name]
+
+[Same structure as Sub-Workflow 1...]
+
+---
+
+## Database Schema
+
+### Tables Involved
+
+| Table | Purpose | Key Fields |
+|-------|---------|------------|
+| `table_1` | [Purpose] | `field_a`, `field_b` |
+| `table_2` | [Purpose] | `field_c`, `field_d` |
+
+### Relationships
+
+```
+table_1 ─┬─< table_2 (one-to-many via foreign_key)
+         └─< table_3 (one-to-many via other_key)
+```
+
+### Schema Notes
+
+[Any important schema considerations, constraints, indexes, etc.]
+
+---
+
+## External APIs
+
+### [API Name 1]
+
+**Base URL:** `https://api.example.com`
+**Authentication:** [Method - API Key, OAuth, etc.]
+**Rate Limits:** [If applicable]
+
+**Endpoints Used:**
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/endpoint` | POST | [What it does] |
+
+**Error Codes:**
+| Code | Meaning | Handling |
+|------|---------|----------|
+| 400 | [Meaning] | [How handled] |
+| 500 | [Meaning] | [How handled] |
+
+---
+
+## Test Coverage
+
+### E2E Tests
+
+| Test File | Test Name | Coverage |
+|-----------|-----------|----------|
+| `tests/e2e/test_file.ext` | `test_scenario` | Sub-workflows 1-3 |
+
+### Unit Tests
+
+| Test File | Coverage Area |
+|-----------|---------------|
+| `tests/unit/test_file.ext` | Function X, Function Y |
+
+### Coverage Gaps
+
+- ❌ [Missing test scenario 1]
+- ❌ [Missing test scenario 2]
+- ⚠️ [Edge case not covered]
+
+### Running Tests
+
+```bash
+# Run all tests for this workflow
+[test command]
+
+# Run specific test
+[specific test command]
+```
+
+---
+
+## Known Gotchas
+
+### Gotcha 1: [Title]
+
+**Severity:** CRITICAL / HIGH / MEDIUM / LOW
+**Symptom:** [What goes wrong]
+**Root Cause:** [Why it happens]
+
+**Fix:**
+```
+[Code or steps to fix]
+```
+
+**Prevention:**
+- [How to avoid in future]
+
+**Workflow Impact:** Sub-Workflow [X] is affected
+
+---
+
+### Gotcha 2: [Title]
+
+[Same structure as Gotcha 1...]
+
+---
+
+## Complete Call Chain
+
+### End-to-End Flow Diagram
+
+```
+[User Action / Trigger]
+         │
+         ▼
+┌─────────────────────┐
+│   Entry Point       │ file.ext:XXX
+│   function_name()   │
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐
+│   Sub-Workflow 1    │
+│   [Name]            │
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐
+│   Sub-Workflow 2    │ ──► [External API]
+│   [Name]            │
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐
+│   Database          │
+│   Operations        │
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐
+│   Response/         │
+│   Completion        │
+└─────────────────────┘
+```
+
+### State Transitions (if applicable)
+
+```
+[STATE_A] ──event──► [STATE_B] ──event──► [STATE_C]
+     │                                        │
+     └──────────── error ────────────────────►│
+                                              ▼
+                                         [STATE_ERROR]
+```
+
+---
+
+## File Reference Table
+
+| File | Size | Purpose | Key Functions |
+|------|------|---------|---------------|
+| `path/file_1.ext` | XX KB | [What it does] | `func_a:XXX`, `func_b:YYY` |
+| `path/file_2.ext` | XX KB | [What it does] | `func_c:ZZZ` |
+| `path/file_3.ext` | XX KB | [What it does] | `func_d:AAA` |
+
+---
+
+## Maintenance Schedule
+
+| Task | Frequency | Last Done | Next Due |
+|------|-----------|-----------|----------|
+| Verify line numbers | Monthly | YYYY-MM-DD | YYYY-MM-DD |
+| Full audit | Quarterly | YYYY-MM-DD | YYYY-MM-DD |
+
+---
+
+## Related Documentation
+
+- **Parent Index:** [WORKFLOW_INDEX.md](../WORKFLOW_INDEX.md)
+- **Related Workflows:** [workflow_2.md](./workflow_2.md)
+- **Responsible Agent:** [agent-name.md](../../agents/agent-name.md)
+
+---
+
+## Change Log
+
+| Date | Change | Commit |
+|------|--------|--------|
+| YYYY-MM-DD | Initial documentation | `hash` |
+
+---
+
+**Version:** 1.0
+**Word Count:** ~XXX words
+**Token Estimate:** ~XX,XXX tokens