How to Create a New CODITECT Workflow

Version: 1.0.0 Last Updated: 2025-12-12 License: Proprietary. LICENSE.txt has complete terms

---

Quick Start

# 1. Copy template
cp CODITECT-CORE-STANDARDS/TEMPLATES/WORKFLOW-TEMPLATE.md \
   workflows/[category]/[workflow-name].workflow.md

# 2. Edit the workflow
# Fill in frontmatter, steps, QA gates

# 3. Validate
/qa validate workflows/[category]/[workflow-name].workflow.md

# 4. Register
python3 scripts/register-workflow.py workflows/[category]/[workflow-name].workflow.md

# 5. Test
/workflow [workflow-name] --dry-run

---

Naming Conventions for Agent Discoverability

Critical: Names Must Be Agent-Callable

Workflows are invoked by agents via the Task tool. Names must be:

1. Descriptive - Clearly indicate purpose
2. Action-Oriented - Start with verb or noun indicating action
3. Searchable - Contain keywords agents will look for
4. Unique - No collisions with commands or other workflows

Naming Patterns

Pattern	Format	Example	Use For
Action-Object	verb-noun	create-project	Creation workflows
Object-Action	noun-verb	code-review	Process workflows
Object-State	noun-state	project-setup	Setup/config workflows
Cycle-Type	noun-cycle	release-cycle	Iterative workflows
Quick-Action	quick-noun	quick-commit	Fast utility workflows
Full-Process	full-noun	full-deploy	Comprehensive workflows

Agent Search Keywords

Agents search for workflows using these patterns:

# Agent will search for workflows matching:
"workflow for {task}"
"create {thing}"
"{thing} workflow"
"how to {action}"

Name your workflow so it matches these searches:

User/Agent Intent	Good Name	Bad Name
"Create a new project"	project-create	init-proj
"Review my code"	code-review	cr-flow
"Deploy to production"	deploy-production	prod-push
"Run security scan"	security-scan	sec-chk
"Set up CI/CD"	cicd-setup	pipeline-cfg

Naming Rules

1. Use full words - documentation not docs, configuration not cfg
2. Be specific - deploy-staging not just deploy
3. Include domain - api-test not just test
4. Max 40 chars - Keep readable but complete
5. No abbreviations - Unless universally understood (API, CI, CD, QA)

Category Prefixes (Optional but Recommended)

For disambiguation, consider category prefixes:

project-create          # Project lifecycle
dev-session-start       # Developer experience
qa-full-validation      # Quality assurance
ops-deploy-staging      # DevOps
doc-generate-api        # Documentation
collab-code-review      # Collaboration
sec-vulnerability-scan  # Security
perf-profile-app        # Performance
ctx-session-save        # Memory/Context
proto-rapid-build       # Innovation

---

Step-by-Step Creation Process

Step 1: Identify the Need

Before creating a workflow, answer:

• What problem does this solve?
• Who will use it? (Human, Agent, Both)
• What triggers it? (Command, Hook, Schedule, Event)
• What outputs does it produce?
• Does a similar workflow already exist?

Step 2: Choose Category and Name

# List existing workflows in category
ls workflows/[category]/

# Check name doesn't conflict
grep -r "name: proposed-name" workflows/

Category Selection:

Your Workflow Does...	Category
Creates/manages projects	project-lifecycle
Helps daily development	developer-experience
Tests/validates quality	quality-assurance
Deploys/manages infra	devops
Creates/updates docs	documentation
Coordinates team work	collaboration
Audits/enforces security	security
Optimizes/monitors perf	performance
Manages session context	memory-context
Prototypes/experiments	innovation

Step 3: Create Workflow File

# Create category directory if needed
mkdir -p workflows/[category]

# Copy template
cp CODITECT-CORE-STANDARDS/TEMPLATES/WORKFLOW-TEMPLATE.md \
   workflows/[category]/[workflow-name].workflow.md

Step 4: Define Frontmatter

Required fields:

---
name: workflow-name  # Must match filename without .workflow.md
description: Clear description for agent discovery (50-200 chars)
license: Proprietary. LICENSE.txt has complete terms
version: 1.0.0
category: [one of 10 categories]
status: draft  # Start as draft

trigger:
  type: command
  value: /workflow-name  # Usually matches name

inputs:
  - name: primary_input
    type: string
    required: true
    description: Clear description for agents

outputs:
  - name: primary_output
    type: file
    description: What agents receive

dependencies:
  agents: [list, agents, used]
  commands: [list, commands, used]
  skills: []
  scripts: []

qa_integration:
  validation: required  # Always require for production
  review: recommended
  gate_score: 80

complexity: simple | moderate | complex
estimated_duration: 5-15m
composable: true
tags: [searchable, keywords, for, agents]
---

Step 5: Write Steps

Each step must have:

1. Clear Name - Descriptive, action-oriented
2. Component Reference - Exact agent/command/script
3. Purpose - Single sentence
4. Invocation - Exact command/code
5. Success Criteria - Checkable conditions
6. Failure Handling - What to do on error

Template for each step:

### Step N: Descriptive Name

**Component:** `type/name` (e.g., `agent/component-qa-validator`)
**Purpose:** What this step accomplishes

#### Invocation

\`\`\`bash
/command --arg value
\`\`\`

#### Success Criteria
- [ ] Specific, verifiable criterion
- [ ] Another criterion

#### Failure Handling
- **Retry:** Yes/No
- **On Failure:** fail-workflow | skip | escalate

Step 6: Add QA Integration

Every production workflow needs QA:

### Step N: Quality Validation

**Component:** `agent/component-qa-validator`
**Purpose:** Ensure outputs meet CODITECT standards

#### Invocation

\`\`\`bash
/qa validate $PREVIOUS_OUTPUT --min-score 80
\`\`\`

#### Gate Criteria
- Score >= 80%: Proceed
- Score < 80%: Block and fix

For complex/release workflows, add deep review:

### Step N+1: Quality Review

**Component:** `agent/component-qa-reviewer`
**Purpose:** Deep quality assessment

#### Invocation

\`\`\`bash
/qa review $VALIDATED_OUTPUT --release-check
\`\`\`

Step 7: Validate Workflow

# Run QA validation on the workflow itself
/qa validate workflows/[category]/[workflow-name].workflow.md

# Check score is >= 80%

Step 8: Test Workflow

# Dry run (no actual execution)
/workflow [workflow-name] --dry-run

# Test with sample inputs
/workflow [workflow-name] --input1 "test" --verbose

Step 9: Register and Activate

# Register in workflow registry
python3 scripts/register-workflow.py workflows/[category]/[workflow-name].workflow.md

# Update status to production
# Edit frontmatter: status: production

# Re-validate
/qa validate workflows/[category]/[workflow-name].workflow.md --strict

---

Workflow Validation Checklist

Required (Must Pass for Production)

• File in correct location: workflows/[category]/[name].workflow.md
• Name matches filename
• Description 50-200 characters
• License: Proprietary. LICENSE.txt has complete terms
• Category is valid
• Trigger defined
• At least 3 steps
• Each step has all required sections
• QA integration defined
• "When to Use" section complete
• Outputs documented

Recommended

• Prerequisites listed
• Error handling table
• Related workflows linked
• Tags are searchable keywords
• Examples use realistic values
• Tested with --dry-run

---

Common Patterns

Pattern 1: Validate-Transform-Output

Step 1: Validate inputs
Step 2: Transform/process
Step 3: QA validate results
Step 4: Output/deliver

Pattern 2: Gather-Analyze-Act

Step 1: Gather context (memory-context-agent)
Step 2: Analyze situation
Step 3: Execute action
Step 4: Validate results
Step 5: Report/checkpoint

Pattern 3: Multi-Stage Gate

Step 1: Initial work
Step 2: QA validation (gate 1)
Step 3: More work
Step 4: QA validation (gate 2)
Step 5: Final QA review
Step 6: Output

Pattern 4: Parallel-Merge

Step 1: Setup
Step 2a: Parallel task A  ─┐
Step 2b: Parallel task B  ─┼─> Step 3: Merge results
Step 2c: Parallel task C  ─┘
Step 4: Validate merged
Step 5: Output

---

Integration with QA Agents

component-qa-validator (Fast/Automated)

Use for:

• File format validation
• Structural compliance
• Quick quality gates
• CI/CD integration

qa_integration:
  validation: required
  gate_score: 80

component-qa-reviewer (Deep/Detailed)

Use for:

• Release validation
• Complex quality assessment
• Documentation review
• Security-sensitive workflows

qa_integration:
  review: required
  gate_score: 85

---

Troubleshooting

"Workflow not found by agent"

Cause: Name not discoverable Fix: Rename with clear, searchable keywords

"QA validation fails"

Cause: Missing required sections Fix: Run /qa validate --verbose to see gaps

"Steps fail with component not found"

Cause: Dependency not registered Fix: Check dependencies in frontmatter, ensure components activated

"Workflow too slow"

Cause: Sequential steps that could be parallel Fix: Add parallel_steps configuration

---

Examples

See workflows/ directory for production examples:

• workflows/project-lifecycle/project-create.workflow.md
• workflows/quality-assurance/qa-full-validation.workflow.md
• workflows/developer-experience/dev-session-start.workflow.md

---

Related Standards:

• CODITECT-STANDARD-WORKFLOWS.md
• CODITECT-STANDARD-AGENTS.md
• CODITECT-STANDARD-COMMANDS.md

---

Maintainer: CODITECT Core Team Compliance: CODITECT Standards Framework v1.0