@cleocode/core 2026.4.4 → 2026.4.6

package/src/validation/protocols/protocols-markdown/research.md

@@ -0,0 +1,261 @@
+---
+id: RSCH
+title: Research Protocol
+version: 1.0.0
+status: active
+type: base
+audience: [llm-agent, orchestrator]
+tags: [research, investigation, evidence]
+skillRef: ct-research-agent
+lastUpdated: 2026-02-24
+enforcement: strict
+---
+
+# Research Protocol
+
+**Provenance**: @task T3155, @epic T3147
+**Version**: 1.0.1
+**Type**: Conditional Protocol
+**Max Active**: 3 protocols (including base)
+
+---
+
+## Trigger Conditions
+
+This protocol activates when the task involves:
+
+| Trigger | Keywords | Context |
+|---------|----------|---------|
+| Investigation | "research", "investigate", "explore", "study" | Information gathering |
+| Analysis | "analyze", "compare", "evaluate", "assess" | Data synthesis |
+| Discovery | "find out", "discover", "learn about" | New information |
+| Documentation | "document findings", "report on" | Structured output |
+
+**Explicit Override**: `--protocol research` flag on task creation.
+
+---
+
+## Requirements (RFC 2119)
+
+### MUST
+
+| Requirement | Description |
+|-------------|-------------|
+| RSCH-001 | MUST NOT implement code or make changes to codebase |
+| RSCH-002 | MUST document all sources with citations |
+| RSCH-003 | MUST write findings to `claudedocs/agent-outputs/` |
+| RSCH-004 | MUST append entry to `MANIFEST.jsonl` |
+| RSCH-005 | MUST return only completion message (no content in response) |
+| RSCH-006 | MUST include 3-7 key findings in manifest entry |
+| RSCH-007 | MUST set `agent_type: "research"` in manifest |
+
+### SHOULD
+
+| Requirement | Description |
+|-------------|-------------|
+| RSCH-010 | SHOULD use multiple independent sources |
+| RSCH-011 | SHOULD cross-reference findings for accuracy |
+| RSCH-012 | SHOULD include confidence levels for claims |
+| RSCH-013 | SHOULD identify gaps or areas needing further research |
+| RSCH-014 | SHOULD link research to relevant tasks |
+
+### MAY
+
+| Requirement | Description |
+|-------------|-------------|
+| RSCH-020 | MAY propose follow-up research tasks |
+| RSCH-021 | MAY include visual diagrams or tables |
+| RSCH-022 | MAY compare multiple approaches or solutions |
+
+---
+
+## Output Format
+
+### File Output
+
+```markdown
+# {Research Title}
+
+**Task**: T####
+**Date**: YYYY-MM-DD
+**Status**: complete|partial|blocked
+**Agent Type**: research
+
+---
+
+## Executive Summary
+
+{2-3 sentence summary of findings}
+
+## Research Questions
+
+1. {Question 1}
+2. {Question 2}
+
+## Findings
+
+### {Topic 1}
+
+{Detailed findings with citations}
+
+### {Topic 2}
+
+{Detailed findings with citations}
+
+## Sources
+
+| Source | Type | Relevance |
+|--------|------|-----------|
+| {Source 1} | {documentation|code|external} | {High|Medium|Low} |
+
+## Recommendations
+
+1. {Actionable recommendation 1}
+2. {Actionable recommendation 2}
+
+## Open Questions
+
+- {Unresolved question or gap}
+```
+
+### Manifest Entry
+
+@skills/_shared/manifest-operations.md
+
+Use `cleo research add` to create the manifest entry:
+
+```bash
+cleo research add \
+  --title "Research Title" \
+  --file "YYYY-MM-DD_topic.md" \
+  --topics "topic1,topic2,topic3" \
+  --findings "Finding 1,Finding 2,Finding 3" \
+  --status complete \
+  --task T#### \
+  --agent-type research
+```
+
+---
+
+## Integration Points
+
+### Base Protocol
+
+- Inherits task lifecycle (start, execute, complete)
+- Inherits manifest append requirement
+- Inherits error handling patterns
+
+### Protocol Interactions
+
+| Combined With | Behavior |
+|---------------|----------|
+| specification | Research informs spec decisions |
+| decomposition | Research identifies task structure |
+| consensus | Research provides evidence for voting |
+
+### Handoff Patterns
+
+| Scenario | Handoff Target |
+|----------|----------------|
+| Research identifies implementation need | implementation protocol |
+| Research reveals design decisions needed | specification protocol |
+| Research requires expert validation | consensus protocol |
+
+---
+
+## Example
+
+**Task**: Research authentication patterns for CLEO plugin system
+
+**Manifest Entry Command**:
+```bash
+cleo research add \
+  --title "Authentication Patterns Research" \
+  --file "2026-01-26_auth-patterns.md" \
+  --topics "authentication,plugins,security" \
+  --findings "OAuth2 is standard for plugin auth,Token refresh needed for long sessions,Rate limiting prevents abuse" \
+  --status complete \
+  --task T2398 \
+  --epic T2392 \
+  --actionable \
+  --needs-followup T2400 \
+  --agent-type research
+```
+
+**Return Message**:
+```
+Research complete. See MANIFEST.jsonl for summary.
+```
+
+---
+
+## Enforcement
+
+### Tool Allowlist
+
+**Allowed Tools** (Read-only operations):
+- `Read` - File reading
+- `Grep` - Content search
+- `Glob` - File pattern matching
+- `Bash` - **Read-only commands only** (ls, cat, grep, find, etc.)
+
+**Prohibited Tools**:
+- `Write` - File writing
+- `Edit` - File modification
+- **Any** code compilation or execution
+
+**Rationale**: Research must remain read-only to prevent contamination of implementation tasks.
+
+### Validation Command
+
+**Command** (planned): `cleo research validate [--task TASK_ID]`
+
+**Current State**: Available via `validate_research_protocol()` in `lib/protocol-validation.sh`
+
+```bash
+# Programmatic validation
+source lib/protocol-validation.sh
+result=$(validate_research_protocol "T1234" "$manifest_entry" "false")
+```
+
+**Checks**:
+- RSCH-001: No code changes in git diff
+- RSCH-004: Manifest entry appended
+- RSCH-006: 3-7 key findings
+- RSCH-007: agent_type = "research"
+
+### Orchestrator Integration
+
+**Pre-Spawn Validation**:
+```bash
+# In lib/orchestrator-spawn.sh Step 6.5
+protocol_type=$(_osp_skill_to_protocol "ct-research-agent")  # Returns "research"
+validate_research_protocol "$task_id" "$manifest_entry" "false"
+# Blocks spawn on MUST violations with EXIT_PROTOCOL_RESEARCH (60)
+```
+
+**Post-Completion Verification**:
+- Git diff analysis detects code modifications
+- Manifest parsing validates key_findings count
+- Agent type verification
+
+### Exit Codes
+
+- `EXIT_PROTOCOL_RESEARCH` (60) - Research protocol violation
+- Common violations: Code changes detected, wrong agent_type, insufficient findings
+
+---
+
+## Anti-Patterns
+
+| Pattern | Why Avoid |
+|---------|-----------|
+| Implementing code during research | Pollutes research context, mixes concerns |
+| Returning findings in response | Wastes orchestrator context |
+| Single-source conclusions | Risk of bias or error |
+| Vague findings without evidence | Not actionable |
+| Skipping manifest entry | Breaks orchestrator workflow |
+
+---
+
+*Protocol Version 1.0.0 - Research Protocol*

package/src/validation/protocols/protocols-markdown/specification.md

@@ -0,0 +1,300 @@
+---
+id: SPEC
+title: Specification Protocol
+version: 1.0.0
+status: active
+type: conditional
+audience: [llm-agent, orchestrator]
+tags: [specification, requirements, rfc2119]
+skillRef: ct-spec-writer
+lastUpdated: 2026-02-24
+enforcement: strict
+---
+
+# Specification Protocol
+
+**Provenance**: @task T3155, @epic T3147
+**Version**: 1.0.1
+**Type**: Conditional Protocol
+**Max Active**: 3 protocols (including base)
+
+---
+
+## Trigger Conditions
+
+This protocol activates when the task involves:
+
+| Trigger | Keywords | Context |
+|---------|----------|---------|
+| Design | "spec", "specification", "design", "architect" | System design |
+| Contract | "contract", "interface", "API", "schema" | Interface definition |
+| Definition | "define", "formalize", "standardize" | Precise semantics |
+| Protocol | "protocol", "workflow", "process" | Behavioral rules |
+
+**Explicit Override**: `--protocol specification` flag on task creation.
+
+---
+
+## Requirements (RFC 2119)
+
+### MUST
+
+| Requirement | Description |
+|-------------|-------------|
+| SPEC-001 | MUST use RFC 2119 keywords for requirements |
+| SPEC-002 | MUST include version number and status |
+| SPEC-003 | MUST define scope and authority |
+| SPEC-004 | MUST include conformance criteria |
+| SPEC-005 | MUST document related specifications |
+| SPEC-006 | MUST use structured format (tables, schemas) |
+| SPEC-007 | MUST set `agent_type: "specification"` in manifest |
+
+### SHOULD
+
+| Requirement | Description |
+|-------------|-------------|
+| SPEC-010 | SHOULD include examples for each requirement |
+| SPEC-011 | SHOULD document failure modes |
+| SPEC-012 | SHOULD specify error handling |
+| SPEC-013 | SHOULD include changelog |
+
+### MAY
+
+| Requirement | Description |
+|-------------|-------------|
+| SPEC-020 | MAY include implementation guidance |
+| SPEC-021 | MAY reference external standards |
+| SPEC-022 | MAY define extension points |
+
+---
+
+## Output Format
+
+### Specification Structure
+
+```markdown
+# {Specification Title}
+
+**Version**: X.Y.Z
+**Status**: DRAFT|ACTIVE|DEPRECATED
+**Created**: YYYY-MM-DD
+**Updated**: YYYY-MM-DD
+**Epic**: T####
+
+---
+
+## RFC 2119 Conformance
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+document are to be interpreted as described in BCP 14 [RFC 2119] [RFC 8174].
+
+---
+
+## Part 1: Preamble
+
+### 1.1 Purpose
+
+{Why this specification exists}
+
+### 1.2 Scope
+
+{What this specification covers and excludes}
+
+### 1.3 Authority
+
+This specification is **AUTHORITATIVE** for:
+- {Area 1}
+- {Area 2}
+
+This specification **DEFERS TO**:
+- {Related spec 1}
+- {Related spec 2}
+
+---
+
+## Part 2: {Main Content}
+
+### 2.1 {Section}
+
+{Content with RFC 2119 requirements}
+
+| Requirement | Description |
+|-------------|-------------|
+| REQ-001 | {MUST/SHOULD/MAY} {requirement} |
+
+### 2.2 Schema
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/schema.json",
+  "type": "object",
+  "properties": {}
+}
+```
+
+---
+
+## Part 3: Conformance
+
+### 3.1 Conformance Classes
+
+A conforming implementation MUST:
+- {Requirement 1}
+- {Requirement 2}
+
+A conforming implementation MAY:
+- {Optional extension}
+
+---
+
+## Part 4: Related Specifications
+
+| Document | Relationship |
+|----------|--------------|
+| {Spec Name} | {AUTHORITATIVE|DEFERS TO|Related} |
+
+---
+
+## Appendix A: Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | YYYY-MM-DD | Initial specification |
+
+---
+
+*End of Specification*
+```
+
+### Version Semantics
+
+| Version Change | When |
+|----------------|------|
+| Major (X.0.0) | Breaking changes to requirements |
+| Minor (X.Y.0) | New requirements, backward compatible |
+| Patch (X.Y.Z) | Clarifications, typo fixes |
+
+### Status Lifecycle
+
+```
+DRAFT -> ACTIVE -> DEPRECATED
+          |
+          +-> SUPERSEDED (by new spec)
+```
+
+### File Output
+
+```markdown
+# {Specification Title}
+
+**Task**: T####
+**Date**: YYYY-MM-DD
+**Status**: complete|partial|blocked
+**Agent Type**: specification
+
+---
+
+## Summary
+
+{2-3 sentence summary of what this spec defines}
+
+## Key Definitions
+
+| Term | Definition |
+|------|------------|
+| {Term} | {Definition} |
+
+## Requirements Summary
+
+| ID | Level | Requirement |
+|----|-------|-------------|
+| REQ-001 | MUST | {Requirement} |
+
+## Open Questions
+
+- {Questions needing resolution}
+```
+
+### Manifest Entry
+
+@skills/_shared/manifest-operations.md
+
+Use `cleo research add` to create the manifest entry:
+
+```bash
+cleo research add \
+  --title "Specification: Title" \
+  --file "YYYY-MM-DD_specification.md" \
+  --topics "specification,design" \
+  --findings "12 MUST requirements,5 SHOULD requirements,Schema defined" \
+  --status complete \
+  --task T#### \
+  --actionable \
+  --agent-type specification
+```
+
+---
+
+## Integration Points
+
+### Base Protocol
+
+- Inherits task lifecycle (start, execute, complete)
+- Inherits manifest append requirement
+- Inherits error handling patterns
+
+### Protocol Interactions
+
+| Combined With | Behavior |
+|---------------|----------|
+| research | Research informs spec decisions |
+| consensus | Consensus resolves spec ambiguities |
+| implementation | Spec guides implementation |
+
+### Review Patterns
+
+| Aspect | Review Focus |
+|--------|--------------|
+| Completeness | All requirements have RFC 2119 level |
+| Testability | Requirements can be verified |
+| Consistency | No contradicting requirements |
+| Scope | Authority boundaries clear |
+
+---
+
+## Example
+
+**Task**: Define protocol stack architecture
+
+**Manifest Entry Command**:
+```bash
+cleo research add \
+  --title "Specification: Protocol Stack Architecture" \
+  --file "2026-01-26_protocol-stack-spec.md" \
+  --topics "protocol,architecture,subagent" \
+  --findings "Base protocol always loaded,Max 3 active protocols,Conditional loading defined" \
+  --status complete \
+  --task T2401 \
+  --epic T2392 \
+  --actionable \
+  --needs-followup T2404 \
+  --agent-type specification
+```
+
+---
+
+## Anti-Patterns
+
+| Pattern | Why Avoid |
+|---------|-----------|
+| Vague requirements without levels | Cannot verify compliance |
+| Missing version number | Cannot track changes |
+| Undefined scope | Unclear authority |
+| No examples | Hard to implement correctly |
+| Skipping RFC 2119 declaration | Ambiguous requirement levels |
+
+---
+
+*Protocol Version 1.0.0 - Specification Protocol*