CODITECT Standard: Workflows

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

Overview

This standard defines the structure, naming conventions, and requirements for CODITECT-CORE workflows. Workflows are orchestrated sequences of agents, commands, and skills that automate complex development tasks.

Workflow Definition

A workflow is a reusable, composable automation sequence that:

Orchestrates multiple CODITECT components (agents, commands, skills, scripts)
Has defined triggers (command, hook, schedule, event)
Produces measurable outputs
Includes quality gates via QA integration
Can be chained with other workflows

File Location and Naming

Location

coditect-core/
├── workflows/                    # Workflow definitions
│   ├── README.md                 # Workflow library index
│   ├── REGISTRY.json             # Machine-readable registry
│   ├── project-lifecycle/        # Category: Project Lifecycle
│   │   ├── new-project.workflow.md
│   │   ├── project-setup.workflow.md
│   │   └── ...
│   ├── developer-experience/     # Category: Developer Experience
│   ├── quality-assurance/        # Category: Quality Assurance
│   ├── devops/                   # Category: DevOps/Infrastructure
│   ├── documentation/            # Category: Documentation
│   ├── collaboration/            # Category: Collaboration
│   ├── security/                 # Category: Security
│   ├── performance/              # Category: Performance
│   ├── memory-context/           # Category: Memory/Context
│   └── innovation/               # Category: Innovation

Naming Convention

Element	Convention	Example
File name	`kebab-case.workflow.md`	`daily-standup-prep.workflow.md`
Workflow name	`kebab-case`	`daily-standup-prep`
Category folder	`kebab-case`	`developer-experience`

Rules:

Use descriptive, action-oriented names
Maximum 40 characters for workflow name
No abbreviations unless universally understood
Suffix must be .workflow.md

YAML Frontmatter Specification

Required Fields

---
name: workflow-name
description: Brief description of what the workflow accomplishes (50-200 chars)
license: Proprietary. LICENSE.txt has complete terms
version: 1.0.0
category: project-lifecycle | developer-experience | quality-assurance | devops | documentation | collaboration | security | performance | memory-context | innovation
status: draft | experimental | production | deprecated

trigger:
  type: command | hook | schedule | event | manual
  value: /command-name | hook-name | cron-expression | event-name

inputs:
  - name: input_name
    type: string | boolean | number | path | array
    required: true | false
    default: default_value
    description: What this input is for

outputs:
  - name: output_name
    type: string | file | report | artifact
    description: What this output contains

dependencies:
  agents: [agent-name-1, agent-name-2]
  commands: [command-1, command-2]
  skills: [skill-1, skill-2]
  scripts: [script-1.py, script-2.sh]

qa_integration:
  validation: required | recommended | optional | none
  review: required | recommended | optional | none
  gate_score: 80  # Minimum score to proceed (0-100)

complexity: simple | moderate | complex
estimated_duration: 1-5m | 5-15m | 15-30m | 30m+
composable: true | false
tags: [tag1, tag2, tag3]
---

Optional Fields

---
# ... required fields ...

author: Author Name
maintainer: Maintainer Name
created: 2025-12-12
deprecated_by: replacement-workflow-name  # If status: deprecated
prerequisites:
  - Prerequisite condition 1
  - Prerequisite condition 2
related_workflows: [workflow-1, workflow-2]
error_handling: retry | fail-fast | continue | escalate
timeout: 300  # Seconds, 0 = no timeout
---

Workflow Body Structure

Required Sections

# Workflow Name

Brief description of the workflow purpose and value.

## When to Use

✅ **Use this workflow when:**
- Condition 1
- Condition 2
- Condition 3

❌ **Don't use this workflow when:**
- Condition 1
- Condition 2

## Prerequisites

- [ ] Prerequisite 1
- [ ] Prerequisite 2

## Inputs

| Input | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `input_name` | string | Yes | - | Description |

## Steps

### Step 1: Step Name
**Agent/Command:** `agent-name` or `/command`
**Description:** What this step does

```bash
# Example invocation
/command --option value

Success Criteria:

Criterion 1
Criterion 2

On Failure: Action to take

Step 2: Step Name

...

Quality Gates

QA Validation (Step N)

Agent: component-qa-validator Trigger: After step X Minimum Score: 80% On Failure: Block progression / Warn and continue

Outputs

Output	Type	Location	Description
`output_name`	file	`path/to/output`	Description

Error Handling

Error Type	Action	Recovery
Validation failure	Retry	Run /qa fix
Agent timeout	Escalate	Notify user

Upstream: workflow-name - Runs before this
Downstream: workflow-name - Runs after this
Alternative: workflow-name - Similar purpose

---

## Step Definition Format

### Step Structure

```markdown
### Step N: Descriptive Step Name

**Component:** `component-type/component-name`
**Purpose:** Single sentence describing step goal

#### Invocation

```bash
# Command invocation
/command-name --arg1 value1 --arg2 value2

# Or agent invocation via Task tool
Task(subagent_type="agent-name", prompt="...")

# Or script invocation
python3 scripts/script-name.py --args

Inputs

input1: Description (from workflow input or previous step)
input2: Description

Outputs

output1: Description (available to subsequent steps)

Success Criteria

Criterion 1
Criterion 2

Failure Handling

Retry: Yes/No (max 3 attempts)
On Failure: fail-workflow | skip-step | escalate | alternative-path
Rollback: Description of rollback action if needed

---

## Trigger Types

### 1. Command Trigger

```yaml
trigger:
  type: command
  value: /workflow-name
  aliases: [/wf-alias, /short]

User invokes via slash command.

2. Hook Trigger

trigger:
  type: hook
  value: pre-commit | post-commit | pre-push | session-start | session-end
  conditions:
    - file_pattern: "*.py"
    - branch: main

Automatically triggered by git/session hooks.

3. Schedule Trigger

trigger:
  type: schedule
  value: "0 9 * * 1-5"  # Cron: 9am weekdays
  timezone: UTC

Runs on schedule (requires external scheduler).

4. Event Trigger

trigger:
  type: event
  value: pr-opened | pr-merged | build-failed | deploy-complete
  source: github | gitlab | ci-system

Triggered by external events.

5. Manual Trigger

trigger:
  type: manual
  value: null

Only runs when explicitly called by another workflow.

QA Integration Requirements

Validation Levels

Level	When Required	Agent	Gate Score
Required	Production workflows	`component-qa-validator`	80+
Recommended	Experimental workflows	`component-qa-validator`	70+
Optional	Draft workflows	Either	Any
None	Simple utility workflows	N/A	N/A

QA Step Template

### Step N: Quality Validation

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

#### Invocation

```bash
/qa validate [outputs-from-previous-steps] --min-score 80

Gate Criteria

Score >= 80%: Proceed to next step
Score 70-79%: Warn and proceed with caution
Score < 70%: Block and require fixes

On Failure

Run /qa fix [component] for auto-fixable issues
Report issues to user for manual fixes
Re-run validation after fixes

### Deep Review Integration

For complex workflows or release-critical paths:

```markdown
### Step N: Quality Review

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

#### Invocation

```bash
/qa review [outputs] --release-check --min-grade B

Gate Criteria

Grade A (90%+): Approved for release
Grade B (80-89%): Approved with minor improvements noted
Grade C (70-79%): Requires improvements before release
Grade D/F (<70%): Blocked - major rework needed

---

## Composability Rules

### Workflow Chaining

Workflows can be chained using the `chain` directive:

```yaml
chain:
  on_success: [downstream-workflow-1, downstream-workflow-2]
  on_failure: [error-handling-workflow]
  pass_outputs: true  # Pass this workflow's outputs as next workflow's inputs

Workflow Embedding

Embed sub-workflows within a step:

### Step 3: Run Sub-Workflow

**Component:** `workflow/code-review-cycle`
**Purpose:** Execute complete code review sub-workflow

#### Invocation

```bash
/workflow code-review-cycle --input $PREVIOUS_OUTPUT

Outputs

Inherits all outputs from embedded workflow

### Parallel Execution

```yaml
parallel_steps:
  - step: 3
    group: validation
  - step: 4
    group: validation
  - step: 5
    group: validation
# Steps 3, 4, 5 run in parallel; workflow waits for all to complete

Complexity Guidelines

Simple Workflows (3-5 steps)

Single responsibility
No conditional branching
No parallel execution
Estimated duration: 1-5 minutes

Example: quick-commit, format-code, run-tests

Moderate Workflows (5-10 steps)

May include one decision point
May include QA validation gate
Some parallel steps allowed
Estimated duration: 5-15 minutes

Example: feature-branch-setup, code-review-prep, documentation-update

Complex Workflows (10+ steps)

Multiple decision points
Required QA validation and review
Parallel execution groups
Error recovery paths
Estimated duration: 15+ minutes

Example: full-release-cycle, security-audit, new-project-complete

Validation Checklist

Required (Must Pass)

Recommended (Should Pass)

Prerequisites section with checklist
Error handling table
Related workflows section
Complexity matches actual step count
Tags are relevant and searchable
Examples use realistic values

Quality Score Calculation

Score = (Required Passed / Required Total) × 70 + (Recommended Passed / Recommended Total) × 30

Score	Grade	Status
90-100%	A	Production Ready
80-89%	B	Good
70-79%	C	Acceptable
60-69%	D	Needs Work
<60%	F	Failing

Minimum for Production: 80% (Grade B)

Quality Grading Criteria (Weighted)

For automated grading via scripts/qa/grade-workflows.py:

A. Prerequisites Documentation (15%)

A1: Prerequisites/setup section present (8pts)
A2: Required inputs clearly specified with types (7pts)

B. Step Completeness (30%)

B1: Numbered/ordered steps present (10pts)
B2: Each step has expected output or success criteria (10pts)
B3: Steps reference specific CODITECT components (agents/commands/scripts) (10pts)

C. Examples & Walkthroughs (25%)

C1: At least 1 complete walkthrough with code blocks (10pts)
C2: Code examples use fenced blocks with language tags (8pts)
C3: Variant/alternative paths documented (7pts)

D. Integration Points (15%)

D1: Related workflows/components linked (8pts)
D2: Output locations and types specified (7pts)

E. Troubleshooting (15%)

E1: Error handling table or common issues section (8pts)
E2: Debug approach or recovery steps documented (7pts)

Automated Validation:

python3 scripts/qa/grade-workflows.py workflows/category/name.workflow.md

Examples

Minimal Valid Workflow

---
name: quick-format
description: Format code files using project standards and commit changes
license: Proprietary. LICENSE.txt has complete terms
version: 1.0.0
category: developer-experience
status: production
trigger:
  type: command
  value: /quick-format
inputs:
  - name: paths
    type: array
    required: false
    default: ["."]
    description: Paths to format
outputs:
  - name: formatted_files
    type: array
    description: List of formatted files
dependencies:
  commands: [format]
  scripts: [format-code.py]
qa_integration:
  validation: optional
  review: none
  gate_score: 0
complexity: simple
estimated_duration: 1-5m
composable: true
tags: [formatting, quick, code-style]
---

# Quick Format

Format code files using project standards.

## When to Use

✅ **Use this workflow when:**
- Before committing code changes
- After pulling updates with conflicts
- To enforce consistent code style

❌ **Don't use this workflow when:**
- Running in CI (use dedicated CI workflow)
- Files are not code (use appropriate formatter)

## Steps

### Step 1: Detect Files

**Component:** `script/detect-changes.py`
**Purpose:** Find files needing formatting

```bash
python3 scripts/detect-changes.py --paths $PATHS

Success Criteria:

File list generated
Supported file types identified

Step 2: Format Files

Component: command/format Purpose: Apply formatting rules

/format --files $FILE_LIST

Success Criteria:

All files formatted without errors
No syntax errors introduced

Step 3: Report Results

Component: script/format-report.py Purpose: Generate formatting summary

python3 scripts/format-report.py --files $FORMATTED_FILES

Success Criteria:

Summary displayed to user

Outputs

Output	Type	Description
`formatted_files`	array	List of files that were formatted
`summary`	string	Human-readable summary

---

## Related Standards

- [CODITECT-STANDARD-AGENTS.md](CODITECT-STANDARD-AGENTS.md) - Agent creation
- [CODITECT-STANDARD-COMMANDS.md](CODITECT-STANDARD-COMMANDS.md) - Command creation
- [CODITECT-STANDARD-SKILLS.md](CODITECT-STANDARD-SKILLS.md) - Skill creation
- [CODITECT-STANDARD-HOOKS.md](CODITECT-STANDARD-HOOKS.md) - Hook creation
- [STANDARDS-ENFORCEMENT.md](../docs/06-implementation-guides/standards/STANDARDS-ENFORCEMENT.md) - QA enforcement

---

## N8N Compatibility

CODITECT workflows support **dual-format** output for integration with [N8N](https://n8n.io/) workflow automation platform.

### File Formats

| Format | File Extension | Purpose |
|--------|----------------|---------|
| Markdown | `.workflow.md` | Human-readable documentation, CODITECT native |
| N8N JSON | `.workflow.n8n.json` | Machine-executable, N8N import-ready |

### N8N JSON Structure

```json
{
  "name": "workflow-name",
  "meta": {
    "coditect": {
      "version": "1.0.0",
      "category": "category-name",
      "description": "Description",
      "license": "Proprietary. LICENSE.txt has complete terms",
      "status": "production",
      "qa_integration": {
        "validation": "required",
        "gate_score": 80
      }
    }
  },
  "nodes": [
    {
      "id": "node-id",
      "name": "Node Name",
      "type": "n8n-nodes-base.nodeType",
      "position": [x, y],
      "parameters": {}
    }
  ],
  "connections": {
    "Source Node": {
      "main": [[{"node": "Target Node", "type": "main", "index": 0}]]
    }
  }
}

CODITECT Meta Extension

The meta.coditect object stores CODITECT-specific metadata:

"meta": {
  "coditect": {
    "version": "1.0.0",
    "category": "quality-assurance",
    "description": "Workflow description",
    "license": "Proprietary. LICENSE.txt has complete terms",
    "status": "production",
    "complexity": "moderate",
    "estimated_duration": "5-15m",
    "composable": true,
    "tags": ["qa", "validation"],
    "qa_integration": {
      "validation": "required",
      "review": "recommended",
      "gate_score": 80
    },
    "trigger": {
      "type": "command",
      "value": "/workflow-name"
    },
    "dependencies": {
      "agents": ["component-qa-validator"],
      "commands": ["qa"],
      "skills": [],
      "scripts": []
    }
  }
}

N8N Node Type Mapping

CODITECT Component	N8N Node Type
Command execution	`n8n-nodes-base.executeCommand`
Script (Python)	`n8n-nodes-base.executeCommand`
Code logic	`n8n-nodes-base.code`
HTTP/API call	`n8n-nodes-base.httpRequest`
Conditional	`n8n-nodes-base.if`
Set variables	`n8n-nodes-base.set`
Merge results	`n8n-nodes-base.merge`
Manual trigger	`n8n-nodes-base.manualTrigger`
Webhook trigger	`n8n-nodes-base.webhook`
Schedule trigger	`n8n-nodes-base.scheduleTrigger`

QA Gate Implementation in N8N

{
  "id": "qa-gate",
  "name": "QA Validation Gate",
  "type": "n8n-nodes-base.code",
  "parameters": {
    "jsCode": "// CODITECT QA Gate - component-qa-validator\\n// Gate Score: 80%\\n\\nconst score = $input.item.json.qa_score || 0;\\nif (score < 80) {\\n  throw new Error(`QA Gate Failed: ${score}% < 80%`);\\n}\\nreturn $input.item;"
  }
}

Conversion Tools

# Convert markdown workflow to N8N JSON
python3 scripts/workflow-to-n8n.py workflows/category/name.workflow.md

# Convert N8N JSON to markdown workflow
python3 scripts/n8n-to-workflow.py workflows/category/name.workflow.n8n.json

# Validate N8N compatibility
python3 scripts/validate-n8n-workflow.py workflows/category/name.workflow.n8n.json

Templates

Markdown Template: WORKFLOW-TEMPLATE.md
N8N JSON Template: WORKFLOW-N8N-TEMPLATE.json

Changelog

v1.0.0 (2025-12-12)

Initial workflow standard release
Defined 10 workflow categories
Established YAML frontmatter specification
Created step definition format
Integrated QA validation requirements
Added composability rules
Added N8N compatibility specification

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

Overview​

Workflow Definition​

File Location and Naming​

Location​

Naming Convention​

YAML Frontmatter Specification​

Required Fields​

Optional Fields​

Workflow Body Structure​

Required Sections​

Step 2: Step Name​

Quality Gates​

QA Validation (Step N)​

Outputs​

Error Handling​

Related Workflows​

Inputs​

Outputs​

Success Criteria​

Failure Handling​

2. Hook Trigger​

3. Schedule Trigger​

4. Event Trigger​

5. Manual Trigger​

QA Integration Requirements​

Validation Levels​

QA Step Template​

Gate Criteria​

On Failure​

Gate Criteria​

Workflow Embedding​

Outputs​

Complexity Guidelines​

Simple Workflows (3-5 steps)​

Moderate Workflows (5-10 steps)​

Complex Workflows (10+ steps)​

Categories​

1. Project Lifecycle​

2. Developer Experience​

3. Quality Assurance​

4. DevOps/Infrastructure​

5. Documentation​

6. Collaboration​

7. Security​

8. Performance​

9. Memory/Context​

10. Innovation​

Validation Checklist​

Required (Must Pass)​

Recommended (Should Pass)​

Quality Score Calculation​

Quality Grading Criteria (Weighted)​

Examples​

Minimal Valid Workflow​

Step 2: Format Files​

Step 3: Report Results​

Outputs​

CODITECT Meta Extension​

N8N Node Type Mapping​

QA Gate Implementation in N8N​

Conversion Tools​

Templates​

Changelog​

v1.0.0 (2025-12-12)​

Overview

Workflow Definition

File Location and Naming

Location

Naming Convention

YAML Frontmatter Specification

Required Fields

Optional Fields

Workflow Body Structure

Required Sections

Step 2: Step Name

Quality Gates

QA Validation (Step N)

Outputs

Error Handling

Related Workflows

Inputs

Outputs

Success Criteria

Failure Handling

2. Hook Trigger

3. Schedule Trigger

4. Event Trigger

5. Manual Trigger

QA Integration Requirements

Validation Levels

QA Step Template

Gate Criteria

On Failure

Gate Criteria

Workflow Embedding

Outputs

Complexity Guidelines

Simple Workflows (3-5 steps)

Moderate Workflows (5-10 steps)

Complex Workflows (10+ steps)

Categories

1. Project Lifecycle

2. Developer Experience

3. Quality Assurance

4. DevOps/Infrastructure

5. Documentation

6. Collaboration

7. Security

8. Performance

9. Memory/Context

10. Innovation

Validation Checklist

Required (Must Pass)

Recommended (Should Pass)

Quality Score Calculation

Quality Grading Criteria (Weighted)

Examples

Minimal Valid Workflow

Step 2: Format Files

Step 3: Report Results

Outputs

CODITECT Meta Extension

N8N Node Type Mapping

QA Gate Implementation in N8N

Conversion Tools

Templates

Changelog

v1.0.0 (2025-12-12)