# 8. Development

## Development

**Outcome:** Workflow built, internal testing passed **Trigger:** [Workshop](https://internal-docs.theentourageai.com/ai-automator/workshop) complete (credentials already configured in [Credential Request](https://internal-docs.theentourageai.com/ai-automator/credential-request)) **Duration:** 2-4 days per workflow (build + test)

### Quick Reference

| Step | Action                      | Time      |
| ---- | --------------------------- | --------- |
| 1    | Confirm credentials         | 5 min     |
| 2    | Extract specs from proposal | 15-30 min |
| 3    | Generate PRD                | 30 min    |
| 4    | Build workflow              | 2-4 days  |
| 5    | Internal testing            | 1-2 hrs   |
| 6    | Export and save             | 15 min    |

This SOP merges: Workflow Build (3.4) + Internal Testing (3.5). Credentials moved to SOP 6.

***

### Full Guide

#### Part 1: Confirm Credentials (5 min)

Credentials were configured and tested during SOP 6 (Credential Request Call). Before starting development, confirm they're ready:

**Quick Check**

1. Open `settings.json` — all credentials should show `"status": "verified"`
2. Open n8n — credentials should already exist with green checkmarks

**If everything is verified:** Proceed to Part 2 (Extract Specs).

**If Additional Systems Discovered in Workshop**

Workshop (SOP 7) may have identified systems not in the original proposal.

**Do NOT request credentials via email** — this is a security risk.

For any new credentials needed:

1. Follow SOP 6 process (schedule a brief credential call)
2. Credentials must be created on a call, tested in n8n, stored in 1Password
3. Update settings.json when complete

**Credential Naming Convention**

| Platform | Naming Pattern          |
| -------- | ----------------------- |
| Gmail    | `{CODE}-Gmail-OAuth2`   |
| HubSpot  | `{CODE}-HubSpot-OAuth2` |
| Slack    | `{CODE}-Slack-Bot`      |

***

#### Part 2: Extract Specs from Proposal (15-30 min)

Before building, extract all features from the client's sales proposal into a structured checklist.

**Locate the Proposal**

1. Check `clients/{CODE}/context/docs/` for the sales proposal PDF
2. If not present, request from sales team or check Google Drive

**Extract Features to JSON**

For each feature/workflow promised in the proposal, create a spec entry:

```json
{
  "specs": [
    {
      "id": "SPEC-001",
      "name": "Invoice Processing Automation",
      "description": "Auto-extract data from supplier invoices and push to Xero",
      "status": "pending",
      "trigger": {
        "type": "email",
        "details": "Invoices arrive at invoices@client.com"
      },
      "integrations": ["Gmail", "Xero", "Google Sheets"],
      "outputs": [
        "Invoice data extracted",
        "Xero bill created",
        "Audit log updated"
      ],
      "priority": "high",
      "complexity": "medium",
      "notes": ""
    }
  ]
}
```

**Spec Fields Reference**

| Field          | Required | Description                            |
| -------------- | -------- | -------------------------------------- |
| `id`           | Yes      | `SPEC-001`, `SPEC-002`, etc.           |
| `name`         | Yes      | Feature name from proposal             |
| `description`  | Yes      | What it does (1-2 sentences)           |
| `status`       | Yes      | `pending` → `in_progress` → `complete` |
| `trigger`      | Yes      | What starts this workflow              |
| `integrations` | Yes      | Systems involved                       |
| `outputs`      | Yes      | What gets created/updated              |
| `priority`     | No       | `high`, `medium`, `low`                |
| `complexity`   | No       | `low`, `medium`, `high`                |
| `notes`        | No       | Implementation notes                   |

**Save to settings.json**

Add the `specs` array to the client's `settings.json`:

```bash
# Location
clients/{CODE}/settings.json
```

The specs array goes at the top level, after `_metadata`.

**Verify Extraction**

* [ ] All features from proposal captured
* [ ] Each spec has id, name, description, trigger, integrations, outputs
* [ ] All specs start with `status: "pending"`
* [ ] settings.json validates (no JSON errors)

***

#### Part 3: Workflow Build (2-4 days)

**Generate PRD**

```
/create:n8n-workflow-prd {CODE}
```

Creates task list with test fixtures based on TECHNICAL-BLUEPRINT.md.

**Workflow Architecture**

```
Trigger → Extract → Process → Integrate → Notify → Log
```

| Layer     | Purpose                        |
| --------- | ------------------------------ |
| Trigger   | What starts the workflow       |
| Extract   | Pull data from trigger         |
| Process   | Apply business logic           |
| Integrate | Write to external systems      |
| Notify    | Send alerts/confirmations      |
| Log       | Record execution for debugging |

**Architecture Pattern: Single Workflow with Test Harness**

Build as **one giant workflow** (not split into sub-workflows unless absolutely necessary).

**Required structure:**

```
[Production Trigger] → [Set Node (Test Harness)] → [Extract] → [Process] → [Integrate] → [Notify] → [Log]
```

| Component               | Purpose                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------- |
| Production Trigger      | Webhook, email trigger, or schedule that will run in production                        |
| Set Node (Test Harness) | Allows programmatic testing by injecting test data without triggering the real trigger |
| Rest of workflow        | Business logic as designed                                                             |

**Why this pattern:**

* Test the ENTIRE workflow without waiting for real triggers
* Same code path for testing and production
* Easy to inject edge cases via the Set node

**Credentials: Fetch from 1Password**

All credentials should be:

1. Created during the Credential Request Call (SOP 6)
2. Stored in the client's 1Password vault: `{CODE} - {Client Name}`
3. Configured in n8n using values from 1Password

**Never accept credentials via email, chat, or text.**

**Build Steps**

1. Create workflow: `{CODE} - {Workflow Name}`
2. Build trigger layer (webhook, email, schedule)
3. Add Set node for test harness immediately after trigger
4. Add extraction nodes
5. Add processing nodes (logic, decisions)
6. Add integration nodes (CRM, email, Slack)
7. Add error handling (try/catch)
8. Add logging

**Best Practices**

* Use descriptive node names
* Add comments to complex logic
* Configure error paths for every integration
* Use Variables Set node for config values
* Tag: `status-development`, `client-{CODE}`

**Track Spec Progress**

As you complete each feature:

1. Update `settings.json` → `specs[].status` to `"in_progress"` when starting
2. Update to `"complete"` when feature is working and tested
3. Add any implementation notes to `specs[].notes`

***

#### Part 4: Internal Testing (1-2 hrs)

**Run Test Suite**

```
/test:workflow "{Workflow Name}"
```

**Test Scenarios**

| Type        | What to Test            | Pass Criteria           |
| ----------- | ----------------------- | ----------------------- |
| Happy Path  | Normal valid input      | 100% success            |
| Edge Case   | Missing optional fields | Uses defaults, no crash |
| Error Case  | Invalid input           | Routes to error handler |
| Performance | Normal load             | Under SLA threshold     |

**Test Data Prefixes**

* Email: `test-{timestamp}@theentourageai.com`
* Names: `TEST USER - DO NOT PROCESS`
* IDs: `TEST-123-{date}`

**Pass/Fail Criteria**

| Metric         | Pass          | Fail            |
| -------------- | ------------- | --------------- |
| Happy path     | 100%          | Any failure     |
| Edge cases     | 90%+          | <90%            |
| Error handling | Errors caught | Uncaught errors |

**Test Report**

Save to: `clients/{CODE}/context/testing/test-report-{DATE}.md`

```markdown
# Test Report: {Workflow Name}
Tested: {date}
Environment: dev

| Metric | Value |
|--------|-------|
| Total | X |
| Passed | Y |
| Failed | Z |
| Pass Rate | Y/X% |

## Recommendation
Ready for UAT: YES/NO
```

***

#### Part 5: Export and Save

1. Download workflow JSON from n8n
2. Save to: `clients/{CODE}/workflows/{workflow-name}.json`
3. Update tags: `status-development` → `status-ready`

***

### If Stuck

```
Can't figure out how to build X?
├── Check n8n-mcp skills for patterns
├── Search n8n community forum
├── Check archived workflows for examples
└── Ask SA for architecture guidance
```

***

### Verify

* [ ] Credentials confirmed in settings.json (already verified in SOP 6)
* [ ] Any new credentials from Workshop handled via SOP 6 (not email)
* [ ] All specs extracted from proposal to settings.json
* [ ] PRD generated
* [ ] Workflow uses production trigger + Set node pattern
* [ ] Workflow runs end-to-end with test data
* [ ] All error paths have handlers
* [ ] Spec statuses updated as features completed
* [ ] Test report saved (≥90% pass rate)
* [ ] All specs marked "complete" before UAT handoff
* [ ] Workflow exported to `clients/{CODE}/workflows/`

**Next:** [Dev Check-ins](https://internal-docs.theentourageai.com/ai-automator/dev-check-ins)