# Agent Instructions

This repository is a public reference repository for portable AI-agent phone-call workflows.

## Review and merge policy

Use [docs/community-review-policy.md](./docs/community-review-policy.md) for contribution
tiers, Must Fix severity, proportionate validation, privacy/history exceptions, and
merge decisions. It applies to existing PRs and automated reviews and supersedes
stricter historical review comments. Optional production hardening does not block demos.
All CI checks for the current PR head must complete successfully before merging,
including checks unrelated to the change. Recheck the head and results before merge.

## Language

All repository-facing content must be written in English.

Do not add Chinese text or other non-English prose to repository files unless it is explicitly part of a user-provided example and the maintainer requests it.

## Scope

Keep the repository focused on AI-agent phone-call workflows:

- Agent Skills
- apps
- workflow plugins
- provider adapters
- scheduler recipes
- automation patterns
- safety patterns
- reference implementations

Do not turn this repository into a general voice-agent list, telephony vendor directory, or call-center software list unless the resource directly helps AI agents package phone-call workflows.

## Directory rules

- Put installable Agent Skills in `skills/`.
- Put runnable apps and integration demos in `apps/`.
- Put no-code and low-code workflow plugins in `plugins/`.
- Put long-form guidance in `docs/`.
- Keep provider-specific or host-specific details out of generic skill frontmatter.

## Skill design rules

Use the Agent Skills folder pattern:

```text
skill-name/
├── SKILL.md
├── references/
├── scripts/
└── assets/
```

Do not put `README.md` files inside installable skill directories unless a distribution platform
explicitly requires one in the skill package. Keep any platform-required skill `README.md` concise
and user-facing. Put long-form guidance under `docs/`, preferably `docs/<skill-name>/README.md`,
and keep reusable operational details in `references/` so agents can load them through progressive
disclosure.

Every `SKILL.md` must include YAML frontmatter with at least:

```yaml
---
name: skill-name
description: Clear description of what the skill does and when to use it.
---
```

For portability:

- keep `name` lowercase with hyphens
- keep `description` useful for discovery
- avoid host-specific frontmatter in generic skills
- put host-specific details in `references/`
- use progressive disclosure: keep `SKILL.md` focused and move long details to references

## App design rules

Apps must remain directly tied to AI-agent phone-call workflows.

- Prefer local fake servers, dry runs, or preview modes for tests and demos.
- Do not require live credentials or real outbound calls for default tests.
- Do not depend on unpublished private packages.
- Document setup, side effects, credentials, and cancellation or rollback behavior when applicable.
- Keep demo apps focused. If a demo becomes a reusable tool, keep it under `apps/` and document the supported workflow boundary.

## Plugin design rules

Plugins must remain directly tied to AI-agent phone-call workflows.

- Put no-code and low-code workflow-platform nodes, actions, connectors, templates, and recipes under `plugins/`.
- Document supported triggers, actions, required inputs, expected outputs, credentials, side effects, and rollback or disable behavior.
- Prefer preview, dry-run, or confirmation paths before a plugin can place calls or create recurring jobs.
- Keep platform-specific implementation details inside the plugin directory.

## Phone-call safety rules

Phone calls are real-world side effects.

Every skill, app, or adapter that can place a call must include rules for:

- explicit user intent
- E.164 phone numbers
- masking phone numbers in summaries
- no credential exposure
- no hidden recurring schedules
- no duplicate jobs
- clear cancellation behavior
- boundaries for medical, legal, financial, or emergency content

## Architecture rule

For recurring reminders, use this default architecture:

```text
Host scheduler handles recurrence.
Phone-call provider handles exactly one call per scheduled run.
```

Do not make provider-side recurrence mandatory. Many providers only support one-time calls or one-time scheduled calls.

## Repository conventions

- Follow [docs/git-naming-conventions.md](./docs/git-naming-conventions.md)
  when naming branches, commits, release tags, PR titles, remotes, and stash
  entries.
- Before creating a new branch, validate the candidate with
  `python3 scripts/check_branch_name.py --branch <type>/<short-kebab-summary>`
  or create it through
  `python3 scripts/create_branch.py <type>/<short-kebab-summary>`.

## Validation

After editing, run:

```bash
python3 scripts/validate_repository.py
```