@esotech/contextuate 2.0.0

package/dist/templates/standards/task-workflow.md

@@ -0,0 +1,246 @@
+# Contextuate Task Workflow Standard
+
+> **Purpose:** Standardized structure for multi-session AI tasks that persist across conversations.
+
+---
+
+## When to Use Task Workflow
+
+Use this workflow when:
+- Task spans multiple AI sessions
+- Multiple phases of work required
+- Need to track progress over time
+- Collaborating with multiple AI agents/platforms
+- **Complex Orchestration**: For multi-agent teams, see [Agentic Workflow](agent-workflow.md)
+- Complex project requiring documentation
+
+Don't use for:
+- Simple, single-session tasks
+- Quick questions or lookups
+- Minor code changes
+
+---
+
+## Agentic Orchestration
+
+For complex tasks requiring specialized roles (Archon, Chronos, etc.), this Task Workflow serves as the **Session Governance** layer.
+
+*   **Relationship**: The `task.md` file becomes the "Shared State" (or blackboard) for the Agentic Workflow.
+*   **Orchestrator**: The **Archon** agent manages the `task.md` file, while sub-agents focus on their specific files.
+*   **Reference**: See **[Agentic Workflow Standard](agent-workflow.md)** for the full dispatch protocol.
+
+---
+
+## Directory Structure
+
+```
+docs/ai/tasks/{task-name}/
+├── 00-project-scope.md      # Task definition (required)
+├── 01-{phase-name}.md       # Phase documentation (as needed)
+├── 02-{phase-name}.md
+├── ...
+├── files/                   # Input files, specs, references
+│   └── {relevant-files}
+└── logs/                    # Progress tracking
+    └── {number}-{date}-{summary}.md
+```
+
+### Location
+- All tasks live in `docs/ai/tasks/`
+- This folder is gitignored (user-specific)
+- Each task gets its own subfolder
+
+---
+
+## File Templates
+
+### 00-project-scope.md (Required)
+
+```markdown
+# {Task Name}
+
+> **Status:** {Planning | In Progress | Blocked | Complete}
+> **Created:** {YYYY-MM-DD}
+> **Updated:** {YYYY-MM-DD}
+
+## Objective
+
+{One paragraph describing what this task accomplishes}
+
+## Requirements
+
+- [ ] {Requirement 1}
+- [ ] {Requirement 2}
+- [ ] {Requirement 3}
+
+## Success Criteria
+
+- {Measurable outcome 1}
+- {Measurable outcome 2}
+
+## Phases
+
+| Phase | Description    | Status                    |
+| ----- | -------------- | ------------------------- |
+| 1     | {Phase 1 name} | {Pending/Active/Complete} |
+| 2     | {Phase 2 name} | {Pending/Active/Complete} |
+
+## Constraints
+
+- {Technical constraint}
+- {Timeline constraint}
+- {Resource constraint}
+
+## Open Questions
+
+- [ ] {Question needing resolution}
+```
+
+### Phase Files (01-{name}.md, 02-{name}.md, ...)
+
+```markdown
+# Phase {N}: {Phase Name}
+
+> **Status:** {Pending | Active | Complete}
+> **Started:** {YYYY-MM-DD}
+> **Completed:** {YYYY-MM-DD or blank}
+
+## Objectives
+
+- {Phase objective 1}
+- {Phase objective 2}
+
+## Approach
+
+{Description of how this phase will be executed}
+
+## Deliverables
+
+- [ ] {Deliverable 1}
+- [ ] {Deliverable 2}
+
+## Notes
+
+{Working notes, decisions made, issues encountered}
+
+## Outcome
+
+{Summary of what was accomplished - filled in when complete}
+```
+
+### Log Files (logs/{number}-{date}-{summary}.md)
+
+```markdown
+# Log: {Summary}
+
+> **Date:** {YYYY-MM-DD}
+> **Session:** {number}
+> **Platform:** {Claude Code | Cursor | Copilot | etc.}
+
+## Work Completed
+
+- {Action taken 1}
+- {Action taken 2}
+
+## Decisions Made
+
+- {Decision and rationale}
+
+## Blockers/Issues
+
+- {Issue encountered}
+
+## Next Steps
+
+- {What should be done next}
+```
+
+---
+
+## Naming Conventions
+
+### Task Folders
+- Use lowercase
+- Use hyphens for spaces
+- Be descriptive but concise
+- Examples: `user-auth-refactor`, `api-v2-migration`, `performance-audit`
+
+### Phase Files
+- Prefix with two-digit number: `01-`, `02-`, etc.
+- Use descriptive names: `01-analysis.md`, `02-design.md`
+
+### Log Files
+- Format: `{number}-{YYYY-MM-DD}-{summary}.md`
+- Example: `01-2024-01-15-initial-analysis.md`
+
+---
+
+## Workflow Process
+
+### Starting a Task
+
+1. Create task folder: `docs/ai/tasks/{task-name}/`
+2. Create `00-project-scope.md` with objectives and requirements
+3. Create `files/` folder if you have input materials
+4. Create first log entry
+
+### During Work
+
+1. Update phase files as work progresses
+2. Create log entries for each significant session
+3. Check off requirements as completed
+4. Update status in scope file
+
+### Completing a Task
+
+1. Mark all requirements complete
+2. Update scope status to "Complete"
+3. Write final log entry with summary
+4. Archive or delete if no longer needed
+
+---
+
+## Cross-Platform Considerations
+
+### Platform Detection
+Log entries should note which AI platform performed the work. This helps when:
+- Debugging issues
+- Understanding context limitations
+- Coordinating between platforms
+
+### Context Limits
+Different AI platforms have different context windows. Structure files so:
+- Scope file is self-contained and readable alone
+- Phase files focus on single phases
+- Log files are chronological and scannable
+
+### Handoff
+When switching platforms mid-task:
+1. Create a log entry summarizing current state
+2. Note any platform-specific context
+3. List explicit next steps
+4. Reference relevant files
+
+---
+
+## Best Practices
+
+### Keep It Updated
+- Update scope status regularly
+- Create log entries for significant sessions
+- Check off requirements as completed
+
+### Be Specific
+- Use concrete, measurable requirements
+- Document decisions and rationale
+- Include file paths and code references
+
+### Stay Focused
+- One task per folder
+- Don't mix unrelated work
+- Split large tasks into subtasks if needed
+
+### Clean Up
+- Archive completed tasks periodically
+- Remove obsolete files from `files/`
+- Delete tasks that were abandoned

package/dist/templates/templates/context.md

@@ -0,0 +1,33 @@
+# Project Context
+
+> **Purpose:** Master index for AI assistants working with this project. This is the primary entry point for all AI context.
+> **Directive:** Read this file first. It is the "Brain" of the project.
+
+---
+
+## 1. Project Identity
+
+**Project Name:** {YOUR_PROJECT_NAME}
+
+**Description:** {Brief description of what this project does}
+
+**Tech Stack:**
+- **Languages:** {Language 1}, {Language 2}
+- **Frameworks:** {Framework 1}, {Framework 2}
+- **Infrastructure:** {Database}, {Cloud Provider}
+
+## 2. Key Concepts
+
+### {Concept 1}
+{Explanation of important concept}
+
+### {Concept 2}
+{Explanation of important concept}
+
+---
+
+## 3. Resources
+
+- **Repository:** {URL}
+- **Issue Tracker:** {URL}
+- **Staging/Prod:** {URL}

package/dist/templates/templates/contextuate.md

@@ -0,0 +1,109 @@
+# Contextuate
+
+<!--
+  CONTEXTUATE MANAGED FILE - DO NOT MODIFY
+  This file is generated by the Esotech Framework and will be overwritten during updates.
+  Customize your project context in: docs/ai/context.md
+-->
+
+> **Purpose:** Master entry point for AI assistants. This file bootstraps the Esotech Framework.
+> **Directive:** Read this file first, then follow instructions to load project context.
+
+---
+
+## 1. Project Context
+
+**Read the project-specific context file for details about this project:**
+
+[Project Context](../context.md)
+
+> If `context.md` exists, it contains project identity, tech stack, and custom configurations.
+
+## Framework Usage Guide
+
+This folder (`docs/ai/.contextuate/`) contains the immutable framework definitions. You should use references to these files to "pull in" capabilities only when needed, maintaining token efficiency.
+
+**Do not read all files in this directory at once.**
+
+1.  **Discover**: Read this file (`contextuate.md`) to map the available resources.
+2.  **Select**: Identify the specific agent, tool, or standard relevant to your current task.
+3.  **Load**: Read only that specific file.
+
+For example, if you need to create a new agent, read `docs/ai/.contextuate/tools/agent-creator.tool.md`. You do not need to read the entire standards library unless you are writing code that specifically requires it.
+
+---
+
+## 2. Agent Framework
+
+> **Rule:** If a specialized agent exists for your task, you MUST adopt that persona and read its specific context.
+
+### Agent Registry
+| Task Domain    | Agent        | Context File                                                                             |
+| -------------- | ------------ | ---------------------------------------------------------------------------------------- |
+| General Coding | Base Agent   | [.contextuate/agents/base.md](.contextuate/agents/base.md)                               |
+| Documentation  | Docs Expert  | [.contextuate/agents/documentation-expert.md](.contextuate/agents/documentation-expert.md) |
+| Tools Expert   | Tools Expert | [.contextuate/agents/tools-expert.md](.contextuate/agents/tools-expert.md)               |
+
+### Custom Agents
+Custom agents are stored in `docs/ai/agents/`. Create new agents using the Agent Creator tool.
+
+---
+
+## 3. Tooling Ecosystem
+
+### Framework Tools
+| Tool                   | Purpose                       | Instruction Guide                                                                              |
+| ---------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------- |
+| **Standards Detector** | Analyze code to find patterns | [.contextuate/tools/standards-detector.tool.md](.contextuate/tools/standards-detector.tool.md) |
+| **Quickref Generator** | Condense docs for AI usage    | [.contextuate/tools/quickref.tool.md](.contextuate/tools/quickref.tool.md)                     |
+| **Agent Creator**      | Generate new agent personas   | [.contextuate/tools/agent-creator.tool.md](.contextuate/tools/agent-creator.tool.md)           |
+
+---
+
+## 4. Standards & Conventions
+
+### Coding Standards
+| Language              | Standards File                                                                                                       |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| PHP                   | [.contextuate/templates/standards/php.standards.md](.contextuate/templates/standards/php.standards.md)               |
+| JavaScript/TypeScript | [.contextuate/templates/standards/javascript.standards.md](.contextuate/templates/standards/javascript.standards.md) |
+| Python                | [.contextuate/templates/standards/python.standards.md](.contextuate/templates/standards/python.standards.md)         |
+| Go                    | [.contextuate/templates/standards/go.standards.md](.contextuate/templates/standards/go.standards.md)                 |
+| Java                  | [.contextuate/templates/standards/java.standards.md](.contextuate/templates/standards/java.standards.md)             |
+
+Custom standards can be added in `docs/ai/standards/`.
+
+### Behavioral Guidelines
+**[Behavioral Guidelines](.contextuate/standards/behavioral-guidelines.md)**
+- Verified Truth: Do not speculate.
+- Minimal Intervention: Only change what is requested.
+
+---
+
+## 5. Documentation Strategy
+
+> **Rule:** Store knowledge where it belongs. Do not rely on chat history.
+
+| Content Type            | Location             |
+| ----------------------- | -------------------- |
+| **AI Context**          | `docs/ai/`           |
+| **Custom Agents**       | `docs/ai/agents/`    |
+| **Custom Standards**    | `docs/ai/standards/` |
+| **Quick References**    | `docs/ai/quickrefs/` |
+| **Multi-Session Tasks** | `docs/ai/tasks/`     |
+| **Custom Commands**     | `docs/ai/commands/`  |
+
+### Multi-Session Tasks
+For complex tasks that span multiple sessions:
+1. Read **[Task Workflow](.contextuate/standards/task-workflow.md)**.
+2. Create a folder in `docs/ai/tasks/{task-name}/`.
+3. Maintain a `00-project-scope.md` and log files.
+
+---
+
+## 6. Framework Information
+
+**Esotech Framework** is a standardized AI context framework.
+
+- **Documentation:** https://contextuate.md
+- **Version:** Check `.contextuate/version.json`

package/dist/templates/templates/platforms/AGENTS.md

@@ -0,0 +1,5 @@
+# Contextuate
+
+> **Context:** [docs/ai/.contextuate/contextuate.md](docs/ai/.contextuate/contextuate.md)
+
+Always read the context file above before starting any task.

package/dist/templates/templates/platforms/CLAUDE.md

@@ -0,0 +1,5 @@
+# Contextuate
+
+> **Context:** [docs/ai/.contextuate/contextuate.md](docs/ai/.contextuate/contextuate.md)
+
+Always read the context file above before starting any task.

package/dist/templates/templates/platforms/GEMINI.md

@@ -0,0 +1,5 @@
+# Contextuate
+
+> **Context:** [docs/ai/.contextuate/contextuate.md](docs/ai/.contextuate/contextuate.md)
+
+Always read the context file above before starting any task.

package/dist/templates/templates/platforms/clinerules.md

@@ -0,0 +1,5 @@
+# Contextuate
+
+> **Context:** [docs/ai/.contextuate/contextuate.md](docs/ai/.contextuate/contextuate.md)
+
+Always read the context file above before starting any task.

package/dist/templates/templates/platforms/copilot.md

@@ -0,0 +1,5 @@
+# Contextuate
+
+> **Context:** [docs/ai/.contextuate/contextuate.md](docs/ai/.contextuate/contextuate.md)
+
+Always read the context file above before starting any task.

package/dist/templates/templates/platforms/cursor.mdc

@@ -0,0 +1,9 @@
+---
+description: Contextuate Framework
+globs: 
+---
+# Contextuate
+
+> **Context:** [docs/ai/.contextuate/contextuate.md](docs/ai/.contextuate/contextuate.md)
+
+Always read the context file above before starting any task.

package/dist/templates/templates/platforms/windsurf.md

@@ -0,0 +1,5 @@
+# Contextuate
+
+> **Context:** [docs/ai/.contextuate/contextuate.md](docs/ai/.contextuate/contextuate.md)
+
+Always read the context file above before starting any task.

package/dist/templates/templates/standards/go.standards.md

@@ -0,0 +1,167 @@
+# Go Coding Standards
+
+> **Language:** Go
+> **Generated:** {DATE}
+
+---
+
+## Formatting
+
+### Tooling
+- **Required:** `gofmt` (or `goimports`) must be applied to all files.
+
+### Indentation
+- **Style:** Tabs (Standard Go behavior)
+
+### Line Length
+- **Guideline:** No strict limit, but prefer readability (80-120 chars).
+
+---
+
+## Naming Conventions
+
+### General Rule
+- Use `MixedCaps` or `mixedCaps` (CamelCase).
+- Keep names short and concise.
+
+### Packages
+- **Style:** lowercase, single word
+- **Avoid:** snake_case, camelCase in package names
+- **Example:** `package user`, not `package user_service`
+
+### Interfaces
+- **Style:** Method name + "er" (if single method)
+- **Example:** `Reader`, `Writer`, `Formatter`
+
+### Structs/Interfaces
+- **Exported:** PascalCase (`User`)
+- **Unexported:** camelCase (`userHelper`)
+
+### Functions/Methods
+- **Exported:** PascalCase (`GetUser`)
+- **Unexported:** camelCase (`parseData`)
+
+### Constants
+- **Style:** PascalCase (for exported) or camelCase
+- **Avoid:** UPPER_SNAKE_CASE (unlike other languages)
+- **Example:** `MaxRetries`, not `MAX_RETRIES`
+
+---
+
+## Structure
+
+### File Organization
+```go
+package main
+
+// 1. Imports (grouped: stdlib, third-party, local)
+import (
+    "fmt"
+    "os"
+
+    "github.com/pkg/errors"
+
+    "myproject/internal/user"
+)
+
+// 2. Constants
+const DefaultTimeout = 30
+
+// 3. Types (Structs/Interfaces)
+type Service interface {
+    Do() error
+}
+
+// 4. Factory Functions
+func NewService() Service {
+    return &serviceImpl{}
+}
+
+// 5. Methods
+func (s *serviceImpl) Do() error {
+    return nil
+}
+```
+
+---
+
+## Error Handling
+
+### Pattern
+- **Style:** Check errors immediately. Avoid nesting.
+
+```go
+// GOOD
+f, err := os.Open("file.txt")
+if err != nil {
+    return err
+}
+
+// BAD
+if f, err := os.Open("file.txt"); err == nil {
+    // ...
+}
+```
+
+### Wrapping
+- **Guideline:** Wrap errors with context when passing up the stack.
+- **Example:** `fmt.Errorf("failed to open config: %w", err)`
+
+---
+
+## Documentation
+
+### Comments
+- **Exported identifiers:** MUST have a doc comment starting with the name.
+- **Format:** Complete sentences.
+
+```go
+// User represents a system user.
+type User struct { ... }
+
+// Fetch retrieves the user by ID.
+func (u *User) Fetch(id int) error { ... }
+```
+
+---
+
+## Common Patterns
+
+### Options Pattern
+```go
+// Preferred for complex constructors
+type Option func(*Server)
+
+func WithPort(port int) Option {
+    return func(s *Server) { s.port = port }
+}
+
+func NewServer(opts ...Option) *Server { ... }
+```
+
+### Context
+- **Guideline:** Pass `context.Context` as the first argument to functions performing I/O.
+
+```go
+func (s *Service) GetData(ctx context.Context, id string) error { ... }
+```
+
+---
+
+## Anti-Patterns
+
+```go
+// BAD: Panic in libraries
+func Parse() {
+    if err != nil {
+        panic(err) // Return error instead
+    }
+}
+
+// BAD: Global state
+var db *sql.DB // Use dependency injection
+```
+
+---
+
+*This file should be customized for your project. Replace placeholders with actual values.*