elements-sync

Files (2)

• SKILL.md
• push-to-elements.sh · scripts/

SKILL.md (first lines)

# Elements Sync

## Prerequisites

| Requirement | Check | How to obtain |
|-------------|-------|---------------|
| `ELEMENTS_API_KEY` env var | `echo $ELEMENTS_API_KEY` | Elements Space → Developer → API Tokens → Create |
| `ELEMENTS_SPACE_NAME` env var | `echo $ELEMENTS_SPACE_NAME` | Your Elements Space name (shown in the app URL) |
| `curl` | `curl --version` | Pre-installed on macOS/Linux |

> **Never hardcode credentials.** Always read from environment variables.
> If variables are not set, instruct the user to add them to their shell profile
> or `.env` file and **never commit them to version control**.

---

## Active Job Monitoring (CRITICAL)

When creating multiple items, create them **one by one** and report each result.
Never batch-create without tracking. After all items are created, report:
total created, any failures with error details, and the IDs of created items.

---

## Environment Setup

```bash
# Add to ~/.zshrc or ~/.bash_profile
export ELEMENTS_API_KEY="your-api-key-here"
export ELEMENTS_SPACE_NAME="your-space-name"
```

> Obtain your API key: Elements app → Space Management → Developer → API Tokens → Create API Token.
> The key is shown **only once** — store it in a password manager.

---

## Using the Helper Script

```bash
# Create a Requirement
bash .setup-agents/skills/elements-sync/scripts/push-to-elements.sh requirement \
  --summary "Implement vacation days feature" \
  --what "Users need a way to track remaining vacation days" \
  --priority 1 --impact 2 --risk 1

# Create a Story
bash .setup-agents/skills/elements-sync/scripts/push-to-elements.sh story \
  --summary "As a user I want to see my vacation balance" \
  --description "Display remaining days on the home dashboard" \
  --risk 1

# Create a Story linked to a Requirement
bash .setup-agents/skills/elements-sync/scripts/push-to-elements.sh story \
  --summary "Show vacation balance on dashboard" \
  --requirement-id "642d4765518823ea234f104e" \
  --risk 1
```

---

## API Reference

### Base URL

```
https://api.elements.cloud/v1
```

### Authentication

Every request must include the header:
```
X-API-KEY: $ELEMENTS_API_KEY
```

### Create a Requirement — `POST /requirements`

Required fields: `summary`, `priority`, `impact`, `risk`

```json
{
  "summary": "string (required)",
  "whatIsRequired": "string — what must be done",
  "howItMightBeImplemented": "string — implementation notes",
  "requiredByReason": "string — business justification",
  "requiredBy": "YYYY-MM-DD — target date",
  "priority": 1,
  "impact": 2,
  "risk": 1,
  "tags": ["tag1", "tag2"],
  "release": "Release Name",
  "assignee": "user@example.com"
}
```

`priority`, `impact`, `risk` are integers (typically 1–3, where 1 = high).

### Create a Story — `POST /stories`

Required field: `summary`

```json
{
  "summary": "string (required)",
  "description": "string — As a user I want...",
  "acceptanceCriteria": "string — Given/When/Then",
  "requirement": "requirementId — links story to parent requirement",
  "affectedRoles": ["Role Name"],
  "risk": 1,
  "tags": ["tag1"],
  "release": "Release Name",
  "assignee": "user@example.com",
  "externalId": "US-101 — your tracking ID"
}
```

### Responses

From jterratsdev/smart-deployment, BSD-3-Clause.

More from jterratsdev/smart-deployment