Nathan Development Standards

Standards and patterns for developing within the Nathan project - an n8n-Jira agent automation system.

When to Use

Invoke this skill when:

• Creating or modifying n8n workflow JSON files
• Writing Python code for the Nathan helpers or templating modules
• Designing webhook command contracts
• Building workflow registry configurations
• Implementing spec-driven features via agent-os

Project Architecture

Nathan follows a layered architecture:

text
External Service (Jira) <-- n8n Workflows <-- Python Agent Service
                             (credentials)      (webhook calls)

Core Principle: n8n owns all external credentials. Python services call n8n webhooks with shared secret authentication.

n8n Workflow Standards

For detailed workflow patterns, load references/n8n-workflow-patterns.md.

Standard Workflow Structure

Every webhook workflow must follow this pattern:

text
Webhook --> Validate Secret --> Operation --> Respond to Webhook
               |                   |              |
               v                   v              v
           Unauthorized       Error Response   Success Response
           Response (401)     (500)            (200)

Required Node Pattern

json
{
  "id": "validate-secret",
  "name": "Validate Secret",
  "type": "n8n-nodes-base.if",
  "typeVersion": 2,
  "parameters": {
    "conditions": {
      "conditions": [{
        "leftValue": "={{ $json.headers['x-n8n-secret'] }}",
        "rightValue": "={{ $env.N8N_WEBHOOK_SECRET }}",
        "operator": { "type": "string", "operation": "equals" }
      }]
    }
  }
}

Response Format

All responses must follow this shape:

json
{ "success": true, "data": {...}, "status_code": 200, "error": null }
{ "success": false, "data": {}, "status_code": 500, "error": "message" }

JQL Expression Escaping

In n8n expressions within JSON, escape properly:

| Wrong | Correct | |-------|---------| | .map(x => "${x}") | .map(x => '"' + x + '"') | | .join('\n') | .join('\\n') | | .replaceAll('\n', ' ') | .replaceAll('\\n', ' ') |

Python Standards

For detailed patterns, load references/python-patterns.md.

Module Structure

text
nathan/
  helpers/           # Shared utilities (workflow registry, etc.)
  workflows/         # n8n workflow JSON + registry.yaml per category
  templating/        # YAML-to-JSON template engine
  scripts/           # Standalone runnable scripts

Code Style

python
# Required imports pattern
from __future__ import annotations
from typing import Any
from pathlib import Path
import logging

logger = logging.getLogger(__name__)

# Type hints required, use T | None not Optional[T]
async def trigger_workflow(url: str, params: dict[str, Any]) -> dict[str, Any]:
    ...

Registry Pattern

yaml
# registry.yaml
version: "1.0.0"
description: "Registry description"

commands:
  command_name:
    endpoint: /webhook/endpoint-path
    method: POST
    required_params:
      - param1
    optional_params:
      - param2
    description: What this command does
    example:
      param1: "value"

Spec-Driven Development

Use agent-os commands for feature development:

1. /shape-spec - Initialize and shape specification
2. /write-spec - Write detailed spec document
3. /create-tasks - Generate task list from spec
4. /orchestrate-tasks - Delegate to subagents

Specs live in agent-os/specs/[spec-name]/ with:

• spec.md - Feature specification
• tasks.md - Implementation tasks with checkboxes
• orchestration.yml - Subagent delegation config

Quick Reference

Common Commands

bash
uv sync                              # Install dependencies
uv run pytest                        # Run tests
uv run pytest path/to/test.py -v     # Single test file
uvx ruff check .                     # Lint
uvx ruff format .                    # Format
docker compose -f docker-compose.n8n.yml up -d  # Start n8n

Environment Variables

| Variable | Purpose | |----------|---------| | N8N_WEBHOOK_SECRET | Shared secret for webhook auth | | N8N_API_KEY | n8n Public API key | | JIRA_DOMAIN | Jira Cloud domain | | JIRA_EMAIL | Jira account email | | JIRA_API_TOKEN | Jira API token |

File Naming Conventions

| Type | Convention | Example | |------|------------|---------| | Workflow JSON | kebab-case.json | jira-get-ticket.json | | Python modules | snake_case.py | n8n_workflow_registry.py | | Test files | test_*.py | test_parser.py | | Registry | registry.yaml | per workflow category |