# Backend Conventions

> CLI-specific conventions: npm registry interaction, filesystem operations, JSON handling, settings merge, and configuration patterns for worclaude

- **Type:** Skill
- **Install:** `agentstack add skill-sefaertunc-worclaude-backend-conventions`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sefaertunc](https://agentstack.voostack.com/s/sefaertunc)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [sefaertunc](https://github.com/sefaertunc)
- **Source:** https://github.com/sefaertunc/Worclaude/tree/main/.claude/skills/backend-conventions
- **Website:** https://sefaertunc.github.io/Worclaude/

## Install

```sh
agentstack add skill-sefaertunc-worclaude-backend-conventions
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# CLI & Data Conventions

worclaude is a CLI tool, not a backend service. This skill covers the patterns that serve a similar role to backend conventions: data access (filesystem), external service interaction (npm registry), configuration management, and data format handling (JSON).

## Filesystem Access Patterns

All file operations use `fs-extra` (not raw `fs`):
- `fs.ensureDir()` for creating directories (idempotent)
- `fs.copy()` for template-to-project file copying
- `fs.readJson()` / `fs.writeJson()` for JSON files
- `fs.pathExists()` for existence checks before operations

Cross-platform rules:
- Always `path.join()` — never concatenate with `/`
- Normalize CRLF before hashing (`content.replace(/\r\n/g, '\n')`)
- Use `os.platform()` for OS-specific behavior (notification commands)

File utilities live in `src/utils/file.js`: `copyDirectory()`, `removeDirectory()`.

## npm Registry Interaction

Single external dependency: `https://registry.npmjs.org/worclaude`

```js
// Shared utility: src/utils/npm.js — getLatestNpmVersion()
// - 5-second timeout (AbortController)
// - Returns null on any error (offline, timeout, 404)
// - Used by: upgrade command (self-update check), status command (version display)
```

No auth tokens. No environment variables. Plain HTTPS fetch. Graceful degradation — every caller handles `null` return.

## JSON Handling

### Settings builder flow
```
Read template JSON → JSON.parse() → merge objects → replaceHookCommands() → JSON.stringify()
```

**Critical:** `replaceHookCommands()` operates on the parsed object's string values, not on the full JSON string. The formatter command and notification command are replaced inside individual hook command strings after parsing.

### Settings merge (append-only)
`mergeSettingsPermissionsAndHooks()`:
- Permissions: append new rules to existing array, deduplicate by string equality
- Hooks: append new hooks, check for matcher conflicts before adding
- Never removes or replaces existing user rules

### parseUserJson() two-pass strategy
```
Pass 1: JSON.parse(raw) — handles well-formed JSON
Pass 2: JSON.parse(raw.replace(/\\{/g, '{').replace(/\\}/g, '}')) — handles zsh artifacts
Fail: throw Error('Could not parse JSON: clear message')
```

### Template variable substitution
Template files use `{variable_name}` placeholders (single braces). These are replaced in the parsed object, not in raw JSON strings. Variables: `{project_name}`, `{description}`, `{tech_stack}`, `{formatter_command}`, `{notification_command}`.

## Configuration Management

### workflow-meta.json
The project's state tracker. Created during init, updated during upgrade.

```json
{
  "version": "1.3.4",
  "installedAt": "ISO timestamp",
  "lastUpdated": "ISO timestamp",
  "projectTypes": ["cli"],
  "techStack": ["node"],
  "useDocker": false,
  "universalAgents": ["plan-reviewer", ...],
  "optionalAgents": ["bug-fixer", ...],
  "fileHashes": { "agents/plan-reviewer.md": "sha256", ... }
}
```

**Hash computation:** SHA-256 of CRLF-normalized file content. Used by upgrade and diff commands to detect which files the user has customized vs which are unchanged from install.

**useDocker field:** Added for settings rebuild during upgrade — determines whether docker.json permissions are included.

### Scenario detection (detector.js)
```
No .claude/ AND no CLAUDE.md → Scenario A (fresh)
.claude/ OR CLAUDE.md exists, but no .claude/workflow-meta.json → Scenario B (existing)
.claude/workflow-meta.json exists → Scenario C (upgrade)
```

## Error Handling

CLI-specific error patterns:
- **Malformed user JSON:** `parseUserJson()` throws with clear message naming the file
- **npm registry errors:** return `null`, caller shows "(offline)" or skips version check
- **EACCES on npm install:** catch specifically, suggest `sudo npm install -g worclaude`
- **Corrupted settings.json:** detected during Scenario B merge, shown as clear error, doesn't crash

All errors surface through `display.error()` (Chalk-styled red output), never raw `console.error`.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sefaertunc](https://github.com/sefaertunc)
- **Source:** [sefaertunc/Worclaude](https://github.com/sefaertunc/Worclaude)
- **License:** MIT
- **Homepage:** https://sefaertunc.github.io/Worclaude/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-sefaertunc-worclaude-backend-conventions
- Seller: https://agentstack.voostack.com/s/sefaertunc
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.