add-client

Add Client

Create a new client workspace with a .tentaqles.yaml manifest, identity rules, and CLAUDE.md skeleton. This is the entry point for any new client — everything else (projects, graphs, memory) builds on top of it.

Gather Information

Collect the following from the user. Client name is required; everything else has sensible defaults. If the user provides partial info (e.g., "new client Acme, they use AWS"), fill in what you can and ask only about the gaps.

Field	Required	Example	Notes
Client name	Yes	"Acme Corp"	Used for display
Client slug	Auto	acme-corp	Lowercase, hyphens, derived from name
Cloud provider	No	azure, aws, digitalocean, none	Default: none
Database provider	No	postgresql, snowflake, databricks, supabase, none	Default: none
Git provider	Yes	github, gitlab, azure-devops	No default — must know this
Git email	Yes	[email protected]	The email for commits in this workspace
Git username	Depends	acme-dev	Required for github/gitlab, not for azure-devops
Language	No	en, pt-BR	Default: en
PM tool	No	asana, jira, github-projects, azure-devops, none	Default: none
Workspaces root	No	~/repos	Where client dirs live. Ask if not obvious from cwd.

Determine Workspaces Root

Check if the user is already inside a known workspaces root by looking at cwd. If cwd looks like ~/repos/ or C:\repos\, use that. Otherwise, check plugin config:

echo $CLAUDE_PLUGIN_OPTION_workspaces_root

If still unknown, ask: "Where do your client workspaces live? (e.g., ~/repos or C:\repos)"

Create the Workspace

1. Create directory structure

mkdir -p "{workspaces_root}/{slug}"
mkdir -p "{workspaces_root}/{slug}/.claude/rules"

2. Generate .tentaqles.yaml

Write the manifest file. Map the user's choices to the correct preflight commands:

Preflight commands by provider:

Provider	Preflight command	expected_user value
github	gh auth status --active	GitHub username (e.g. alice-dev) — NEVER the email
gitlab	glab auth status	GitLab username — NEVER the email
azure-devops	git config user.email	(leave expected_user unset — use email check only)
azure (cloud)	az account show --query name -o tsv	— (use cloud.expected: {subscription_name})
aws (cloud)	aws sts get-caller-identity --query Account --output text	— (use cloud.expected: {account_id})
digitalocean	doctl account get --format Email --no-header	— (use cloud.expected: {email})

CRITICAL: For github and gitlab, expected_user must be the CLI username returned by gh auth status --active (parsed from account <name>). It is NOT the email and NOT a display name. The auto-switch hook uses this value in gh auth switch --user <expected_user>. If you put the email here, the switch will always fail because no such account name exists.

When asking the user for git identity, ask separately:

• "What's your git email?" → git.email
• "What's your GitHub/GitLab username?" → git.user AND git.expected_user (set both to the same value)

Blocked commands by provider (safe defaults):

• github: ["gh repo delete", "git push --force main", "git push --force master"]
• gitlab: ["git push --force main", "git push --force master"]
• azure-devops: ["git push --force main", "git push --force master"]
• azure (cloud): ["az group delete", "az keyvault delete", "az storage delete"]
• aws (cloud): ["aws iam delete", "aws s3 rb"]

Write the file:

# Tentaqles client manifest — {display_name}
# Generated by /tentaqles:add-client
schema: tentaqles-client-v1
client: {slug}
display_name: "{display_name}"
language: {language}

cloud:
  provider: {cloud_provider}
  # subscription_name: ""     # fill in after cloud login
  # subscription_id: ""
  preflight: "{cloud_preflight_cmd}"
  expected: "{cloud_expected}"
  blocked_commands: {cloud_blocked}

database:
  provider: {db_provider}
  dialect: {db_dialect}
  host: {db_host}
  access: mcp
  mcp_server: {db_mcp}

git:
  provider: {git_provider}
  email: "{git_email}"
  user: {git_username}
  host: {git_host}
  preflight: "{git_preflight_cmd}"
  expected_user: {git_expected}
  blocked_commands: {git_blocked}

project_management:
  provider: {pm_provider}
  workspace: {slug}

stack: []  # add technologies as projects are created

For fields the user didn't provide (like cloud subscription_name), leave them commented out with instructions to fill in later.

3. Create identity rules

Write .claude/rules/identity.md:

# Identity — {display_name}

- Git commits MUST use email: {git_email}
- Before any git push/commit, verify: `git config user.email` returns `{git_email}`
- Git provider: {git_provider}
{if cloud_provider != 'none':}
- Cloud provider: {cloud_provider}. Verify subscription before any cloud CLI operations.
{endif}
{if language == 'pt-BR':}
- Documentation and commit messages in Portuguese (pt-BR)
{endif}

4. Create CLAUDE.md skeleton

Write CLAUDE.md at the workspace root:

# {display_name}

## Overview
<!-- Describe what this client does, their industry, key products -->

## Tech Stack
<!-- Will be updated as projects are added -->

## Conventions
- Language: {language}
- Git: {git_provider} ({git_email})
{if cloud_provider != 'none':}
- Cloud: {cloud_provider}
{endif}
{if db_provider != 'none':}
- Database: {db_provider} ({db_dialect} dialect)
{endif}

## Development
<!-- Add build commands, test commands, deployment notes as you learn them -->

5. Register in metagraph

python -c "
import sys, os
sys.path.insert(0, os.environ.get('CLAUDE_PLUGIN_ROOT', '.'))
from tentaqles.metagraph.config import register_workspace
register_workspace('{slug}', '{full_path}', '{display_name}')
print('Registered in metagraph')
"

6. Configure git identity

cd "{workspaces_root}/{slug}"
git config user.email "{git_email}"
git config user.name "{user_display_name}"

7. Run preflight checks

python -c "
import sys, os
sys.path.insert(0, os.environ.get('CLAUDE_PLUGIN_ROOT', '.'))
from tentaqles.manifest.loader import load_manifest, run_preflight_checks, format_context_summary, get_client_context
manifest = load_manifest('{full_path}')
ctx = get_client_context('{full_path}')
checks = run_preflight_checks(manifest or ctx)
print(format_context_summary(ctx, checks))
"

8. Report

Summarize what was created:

• Workspace path
• Files created (.tentaqles.yaml, .claude/rules/identity.md, CLAUDE.md)
• Preflight check results (what passed, what needs fixing)
• Next steps: "Create your first project with /tentaqles:add-project"
• Any manual setup needed (cloud login, git config, etc.)

Error Handling

• If the directory already exists and has a .tentaqles.yaml, warn: "This workspace already exists. Do you want to overwrite the manifest?"
• If Python modules aren't available, create the files manually without the metagraph registration step, and note that the user should run pip install tentaqles later.
• If the workspaces root doesn't exist, create it (after confirming with the user).