---
name: team-setup
description: Use when bootstrapping a team directives repository from scratch, cloning an existing one, pointing to a local path, or checking an existing configuration.
---

# team-setup

## Overview

`team-setup` is an interactive skill that guides you through setting up the team AI directives. It presents four modes, explains each option, confirms your choice, and executes the setup.

It is invoked in two ways:
- **User-invoked** (`/team-setup`) — anytime, to configure or check a project.
- **Model-invoked by `team-boot`** — automatically at session start when a project has no `.adlc/init-options.json` configuration (self-install), so an unconfigured project wires itself without the user knowing the command.

The skill is non-destructive: it never overwrites existing files or directories. If the target path already contains a configured team AI directives, it detects this and offers the "Already configured" mode instead.

## When to Use

- Starting a new team from scratch and need a neutral team AI directives scaffold to fill in later.
- Your team already has a directives repo on GitHub and you want to clone it locally.
- You have a local team AI directives directory already (e.g., from a previous project) and want to wire it up.
- You're unsure whether the team AI directives is already configured and want a quick check.
- When the project isn't yet wired to a team AI directives (no `.adlc/init-options.json` `team_ai_directives` field).
- Automatically via `team-boot` when it detects an unconfigured project at session start (self-install).

## Decline Handling (when model-invoked by team-boot)

When `team-boot` invokes this skill because the project is unconfigured, the
user may choose not to set up team AI directives right now. Handle decline
explicitly to avoid a re-prompt loop:

- If the user declines at mode selection, do **not** run any mode. Exit
  cleanly and tell `team-boot` the user declined.
- Offer a persistent opt-out: *"Don't ask again for this project?"* On yes
  (build mode only), write `.adlc/init-options.json` with
  `team_ai_directives: null`:
  ```bash
  echo '{"team_ai_directives": null}' > ".adlc/init-options.json"
  ```
  This marker makes `team-boot` skip setup silently on every future prompt.
- In plan/read-only mode, a persistent opt-out cannot be written — the
  decline is session-scoped only; tell `team-boot` to defer.
- Never force a mode; the setup is user-consented at every step.

## Core Process

### Goal

Set up a team AI directives using one of four modes.

### Security: Input Validation (all modes)

Before executing any mode, validate every user-supplied value (paths, URLs, team
names). These values are interpolated into shell commands; unvalidated input is
a command-injection vector.

- **Paths** (`{DEST}`, `{ABSOLUTE_PATH}`): reject if they contain any of
  `` ` ``, `$`, `;`, `|`, `&`, `(`, `)`, `<`, `>`, newline, or backslash.
  Resolve to an absolute path with `realpath`/`Resolve-Path` before use.
- **Team name**: must match `^[A-Za-z0-9 ._-]+$`. Reject anything else.
- **Clone URL** (Mode 1): must start with `https://`. Reject `file://`, `ssh://`,
  and any non-`https` scheme unless the user explicitly confirms the risk.
  Cloning runs no code from the repo, but the cloned content is read by agents
  later — only clone repositories you trust.

If any value fails validation, report which value and why, and re-ask. Never
interpolate a user value into a Python/eval source string — pass it through the
environment (see Mode 2).

### Mode 1: Clone from GitHub

Clone an existing team-ai-directives repository from GitHub.

**Explore**:
1. Ask the user for the GitHub repository URL (default: `https://github.com/tikalk/agentic-sdlc-team-ai-directives`)
2. Validate the URL starts with `https://` (reject `file://`, `ssh://`, and other schemes — see Input Validation). Only clone repositories you trust; the cloned content is read by agents later.
3. Ask where to clone it (default: `./team-ai-directives`)
4. Check that the destination does not already exist

**Present**:
Show the user:
- Source URL
- Destination path
- Estimated size (from remote repo info if available)

**Confirm**:
```
Clone team-ai-directives from {URL} to {DEST}?
[Y/n]
```

**Write/Execute**:
```bash
git clone "{URL}" "{DEST}"
```

After clone, verify the team AI directives structure exists:
- `{DEST}/context_modules/constitution.md`
- `{DEST}/context_modules/rules/`
- `{DEST}/context_modules/personas/`
- `{DEST}/context_modules/examples/`
- `{DEST}/CDR.md`
- `{DEST}/.skills.json`

Verify the `adlc` orphan branch exists (for CDR drafts and usage reports), create if missing:
```bash
git -C "{DEST}" show-ref --verify --quiet refs/heads/adlc || {
  cd "{DEST}"
  git checkout --orphan adlc
  mkdir -p drafts/cdr reports/sessions reports/projects
  echo '{}' > reports/confidence-scores.json
  touch drafts/cdr/.gitkeep reports/sessions/.gitkeep reports/projects/.gitkeep
  git add -A && git commit -m "Initialize adlc orphan branch (drafts + reports)"
  git checkout main
}
```

### Mode 2: Point to Existing Local Path

Wire an existing local team-ai-directives directory into the project.

**Explore**:
1. Ask the user for the path to their existing team AI directives directory
2. Validate the path exists
3. Validate the team AI directives structure (same checks as Mode 1 post-clone)
4. If validation fails, explain what's missing and ask the user to fix it or choose a different mode

**Present**:
Show the user:
- Resolved absolute path
- Validation results (which required files/dirs exist and which are missing)

**Confirm**:
```
Use existing team-ai-directives at {ABSOLUTE_PATH}?
[Y/n]
```

**Write/Execute**:
Update the project's `.adlc/init-options.json` to set the `team_ai_directives` field to the resolved path. Uses `jq` for safe JSON manipulation — never interpolate user input into shell source.

```bash
# Resolve to an absolute path and validate (see Input Validation)
ABSOLUTE_PATH="$(realpath "$USER_PATH")"

# Write config using jq (merge into existing or create new)
if [ -f ".adlc/init-options.json" ]; then
  jq --arg p "$ABSOLUTE_PATH" '. + {team_ai_directives: $p}' ".adlc/init-options.json" > ".adlc/init-options.json.tmp" && mv ".adlc/init-options.json.tmp" ".adlc/init-options.json"
else
  jq -n --arg p "$ABSOLUTE_PATH" '{team_ai_directives: $p}' > ".adlc/init-options.json"
fi
```

Ensure the `adlc` orphan branch exists (create if missing):
```bash
git -C "$ABSOLUTE_PATH" show-ref --verify --quiet refs/heads/adlc || {
  cd "$ABSOLUTE_PATH"
  git checkout --orphan adlc
  mkdir -p drafts/cdr reports/sessions reports/projects
  echo '{}' > reports/confidence-scores.json
  touch drafts/cdr/.gitkeep reports/sessions/.gitkeep reports/projects/.gitkeep
  git add -A && git commit -m "Initialize adlc orphan branch (drafts + reports)"
  git checkout main
}
```

### Mode 3: Scaffold New Empty team AI directives

Create a fresh, neutral team AI directives at a specified path.

**Explore**:
1. Ask the user where to create the team AI directives (default: `./team-ai-directives`)
2. Ask for the team name
3. Check the destination does not already exist or is empty

**Present**:
Show the user the 10 files that will be created:

| # | File | Purpose |
|---|------|---------|
| 1 | `README.md` | Getting started documentation |
| 2 | `AGENTS.md` | Agent instructions (loading order, rules, skills) |
| 3 | `CDR.md` | Derived CDR index stub (auto-generated by `/team-repair`) |
| 4 | `.skills.json` | Empty skills manifest (schema v2.0.0: `default`/`external`/`blocked`/`policy`) |
| 5 | `.mcp.json.example` | Empty MCP servers config example |
| 6 | `context_modules/constitution.md` | Placeholder constitution (OKF v0.2 frontmatter) — fill via `/team-constitution` |
| 7 | `context_modules/index.md` | OKF v0.2 root index (`okf_version: "0.2"`) linking sub-directories |
| 8 | `context_modules/log.md` | OKF §9 aggregate update log |
| 9 | `context_modules/rules/index.md` | OKF §8 progressive disclosure (rules) |
| 10 | `context_modules/rules/log.md` | OKF §9 rules audit trail |
| 11 | `context_modules/rules/.gitkeep` | Rules directory placeholder |
| 12 | `context_modules/personas/index.md` | OKF §8 progressive disclosure (personas) |
| 13 | `context_modules/personas/log.md` | OKF §9 personas audit trail |
| 14 | `context_modules/personas/.gitkeep` | Personas directory placeholder |
| 15 | `context_modules/examples/index.md` | OKF §8 progressive disclosure (examples) |
| 16 | `context_modules/examples/log.md` | OKF §9 examples audit trail |
| 17 | `context_modules/examples/.gitkeep` | Examples directory placeholder |
| 18 | `skills/.gitkeep` | Skills directory placeholder |

**Confirm**:
```
Scaffold empty team-ai-directives at {DEST} with team name "{TEAM_NAME}"?
[Y/n]
```

**Write/Execute**:

Create directory structure:
```bash
mkdir -p "{DEST}/context_modules/rules"
mkdir -p "{DEST}/context_modules/personas"
mkdir -p "{DEST}/context_modules/examples"
mkdir -p "{DEST}/skills"
```

Create `{DEST}/README.md`:
```markdown
# {TEAM_NAME} Team AI Directives

Team AI directives repository for {TEAM_NAME}.

## Getting Started

1. Wire this directives repository into a project:
   ```
   /team-setup
   ```
   Choose "Point to existing local path" and select this directory.

2. Add context modules to `context_modules/` (rules, personas, examples).

3. Add skills to `skills/` and register them in `.skills.json`.

4. Update `CDR.md` as context modules are approved.

See [ADLC Team Skills](https://github.com/tikalk/adlc-team-skills) for full documentation.
```

Create `{DEST}/AGENTS.md`:
```markdown
# Agent Instructions

## Structure

- `context_modules/constitution.md` — Team constitution
- `context_modules/rules/` — Team rules and workflows
- `context_modules/personas/` — Team personas
- `context_modules/examples/` — Team examples
- `skills/` — Team skills
- `CDR.md` — Context Directive Records

## Loading Order

1. Load constitution.md first
2. Load relevant rules for the current task
3. Load relevant personas for the current task
4. Load relevant examples for the current task

## Using Skills

Skills are located in the `skills/` directory. Browse available skills using `team-skills` and install them as needed.

## CDR.md

CDR.md is a derived flat table, auto-generated by `/team-repair` from per-directory `index.md` files. It is used by `team-boot` for system prompt injection. Do not edit manually — run `/team-repair` to regenerate.
```

Create `{DEST}/CDR.md`:
```markdown
# Context Directive Records (Derived Index)

> ⚠️ Auto-generated by `/team-repair`. Do not edit manually.
> Source of truth: `context_modules/*/index.md` + module frontmatter.
> Decision lifecycle (Accepted/Rejected) lives in the `adlc` orphan branch `drafts/cdr/`.

## CDR Index

| ID | Path | Type | Description | Generated | Verified | Age | Status |
|----|------|------|-------------|-----------|----------|-----|--------|

**Stats**: 0 entries | Last Updated: {TODAY}
```

Create `{DEST}/.skills.json`:
```json
{
  "version": "2.0.0",
  "source": "team-ai-directives",
  "description": "Team skills manifest. The `default` list contains skill names that are auto-installed during project setup. The `external` map contains on-demand skills fetched by URL. The `blocked` list contains skills that must never be installed.",
  "default": [],
  "external": {},
  "blocked": [],
  "policy": {
    "auto_install_default": true,
    "enforce_blocked": true,
    "allow_project_override": true
  }
}
```

Create `{DEST}/.mcp.json.example`:
```json
{
  "mcpServers": {}
}
```

Create `{DEST}/context_modules/constitution.md`:
```markdown
---
type: Constitution
title: "{TEAM_NAME} Constitution"
description: "Team-wide principles and governance"
resource: ./context_modules/constitution.md
tags: [constitution]
generated: { by: agent:team-setup, at: {TODAY}T00:00:00Z }
id: constitution
cdr_ref: null
created: {TODAY}
verified:
  - { by: agent:team-setup, at: {TODAY}T00:00:00Z }
status: stable
stale_after: 180d
---

# {TEAM_NAME} Constitution

No team-wide principles defined yet. Add principles as they are established.
```

Create OKF v0.2-compliant `index.md` and `log.md` files for progressive disclosure:

Create `{DEST}/context_modules/index.md`:
```markdown
---
okf_version: "0.2"
---

# Context Modules

* [Rules](rules/index.md) - Team rules and workflows
* [Personas](personas/index.md) - Team personas
* [Examples](examples/index.md) - Team examples
```

Create `{DEST}/context_modules/log.md`:
```markdown
# Context Modules Update Log
```

Create `{DEST}/context_modules/rules/index.md`:
```markdown
# Rules

No rules defined yet. Use `/team-learn` to create rules via CDRs.
```

Create `{DEST}/context_modules/rules/log.md`:
```markdown
# Rules Update Log
```

Create `{DEST}/context_modules/personas/index.md`:
```markdown
# Personas

No personas defined yet. Use `/team-learn` to create personas via CDRs.
```

Create `{DEST}/context_modules/personas/log.md`:
```markdown
# Personas Update Log
```

Create `{DEST}/context_modules/examples/index.md`:
```markdown
# Examples

No examples defined yet. Use `/team-learn` to create examples via CDRs.
```

Create `{DEST}/context_modules/examples/log.md`:
```markdown
# Examples Update Log
```

Create gitkeep files:
```bash
touch "{DEST}/context_modules/rules/.gitkeep"
touch "{DEST}/context_modules/personas/.gitkeep"
touch "{DEST}/context_modules/examples/.gitkeep"
touch "{DEST}/skills/.gitkeep"
```

Initialize git (required for `/team-learn` branch/commit/PR flow):
```bash
cd "{DEST}" && git init && git add -A && git commit -m "Initial team-ai-directives scaffold"
```

Create the `adlc` orphan branch for CDR drafts and usage reports:
```bash
cd "{DEST}"
git checkout --orphan adlc
mkdir -p drafts/cdr reports/sessions reports/projects
echo '{}' > reports/confidence-scores.json
touch drafts/cdr/.gitkeep reports/sessions/.gitkeep reports/projects/.gitkeep
git add -A
git commit -m "Initialize adlc orphan branch (drafts + reports)"
git checkout main  # back to main branch
```

**Follow-up**: The scaffolded `context_modules/constitution.md` is a placeholder ("No team-wide principles defined yet"). Tell the user:

```text
Scaffold complete. Run /team-constitution next to establish your team's
principles interactively — it detects the placeholder and walks you through
creating the real constitution.
```

After scaffold, run the post-setup configuration (same as Mode 4 below).

### Mode 4: Already Configured

The team AI directives is already configured. Verify and report status.

**Explore**:
1. Check `.adlc/init-options.json` for `team_ai_directives` field
2. If found, resolve the path and validate the team AI directives structure
3. Check `TEAM_AI_DIRECTIVES` env var as fallback
4. Check default path `team-ai-directives` as final fallback

**Present**:
Show the user the resolved team AI directives path and validation results.

**Write/Execute**:
No writes needed — the team AI directives is already configured. Then run the
**MCP config install** (see Post-Setup Configuration step 4): merge
`.mcp.json` servers into the project's config if not already present.

### Mode Selection Flow

1. **Explore**: Present the user with four options:
   ```
   How would you like to set up team-ai-directives?

   1) Clone from GitHub — Clone an existing repository
   2) Point to existing local path — Use a team AI directives you already have
   3) Scaffold new empty team AI directives — Create a fresh neutral team AI directives
   4) Already configured — Check existing configuration
   ```

2. **Present**: For the chosen mode, explain what will happen and show details.

3. **Confirm**: Ask the user to confirm before executing.

4. **Write/Execute**: Perform the setup for the chosen mode.

### Post-Setup Configuration

After any mode completes successfully, update the project configuration:

1. Write `team_ai_directives` to `.adlc/init-options.json`
2. Verify the team AI directives is accessible by running a quick health check:
   - `{TEAM_AI_DIRECTIVES}/context_modules/constitution.md` exists
   - `{TEAM_AI_DIRECTIVES}/.skills.json` exists and is valid JSON
3. Inject the project-level `AGENTS.md` directive so agents auto-invoke `team-boot` at session start:

```bash
# Bash
bash "$(dirname "$0")/team-helpers.sh" --inject-agents "{PROJECT_ROOT}"

# PowerShell
pwsh "$(Split-Path $PSCommandPath -Parent)/team-helpers.ps1" -InjectAgents "{PROJECT_ROOT}"
```

This creates or updates the project's `AGENTS.md` with a managed section (between `<!-- TEAM_AI_DIRECTIVES START -->` and `<!-- TEAM_AI_DIRECTIVES END -->` markers) containing:

- **Event-hook awareness**: notes that `team-boot` runs automatically at session start via the event hook (for agents with event support), injecting a lean orientation into the first user message.
- **Fallback invocation**: "If the team AI directives context is NOT in your system prompt or first user message (agent without event support), invoke the `team-boot` skill before responding to any task or question."
- **Unconfigured handling**: "If team AI directives are unconfigured, invoke the `team-setup` skill."
- **Team Context in Use contract**: "Every response MUST include a Team Context in Use section before the task answer" — a 4-column table (`ID | Name | Type | Rel`) listing genuinely matched CDRs/skills, followed by `_Searched N CDRs, M skills, J matched._`

Without this section, an agent without event support has no session-start instruction to load team context, and the team AI directives repository remains invisible until manually loaded. The section is idempotent: re-running `team-setup` or `team-repair` updates the section in place without duplicating content.

4. **Install MCP config**: Read `{TEAM_AI_DIRECTIVES}/.mcp.json` if it exists, and merge its `mcpServers` configuration into the project's own `.mcp.json` or `.opencode/mcp.json` config. Report which servers were merged, and highlight any unresolved environment variables needed by the servers.

## Common Rationalizations

| Rationalization | Why it's wrong | What to do instead |
|---|---|---|
| "I'll just clone it manually." | Manual cloning skips the `.adlc/init-options.json` wiring, so agents won't find the team AI directives. | Use Mode 1 — it clones AND configures. |
| "I already have a team AI directives directory, I'll just use it." | The directory may be incomplete (missing required files) or not wired in config. | Use Mode 2 — it validates the structure and creates the config entry. |
| "I'll just create a few files by hand." | An incomplete scaffold breaks health checks and agent discovery. | Use Mode 3 — it creates all 10 required files with valid structure. |
| "I'm sure it's already configured." | The path may be stale, moved, or the env var may point to a deleted dir. | Use Mode 4 — it validates the existing configuration. |
| "Scaffolding without a team name is fine." | The team name is used in `README.md` — a blank name makes the team AI directives anonymous and harder to audit. | Always provide a team name in Mode 3. |

## Red Flags

- **Cloning over an existing directory** — Mode 1 refuses if the destination already exists to prevent overwrites.
- **Pointing to a non-existent path** — Mode 2 validates the path exists before proceeding.
- **Scaffolding without required dirs being writable** — Mode 3 creates directories with `mkdir -p` but will fail on permission errors; check permissions first.
- **Skipping the `team_ai_directives` config write** — without this field in `init-options.json`, agents cannot discover the team AI directives.
- **Using a relative path in `init-options.json`** — always resolve to an absolute path so the config is portable across working directories.
- **Skipping `git init` in Mode 3** — a scaffolded team AI directives without git cannot be used by `/team-learn` (branch/commit/PR flow). Mode 3 runs `git init` automatically; if you skip it, run `git init` manually before `/team-learn`.
- **Skipping the project-level AGENTS.md injection** — without the `<!-- TEAM_AI_DIRECTIVES START -->` managed section in the project's `AGENTS.md`, agents without event support have no session-start instruction to load team context. The `.adlc/init-options.json` config alone is insufficient — it tells skills where the team AI directives is, but nothing tells the agent to check. (For agents with event support, the session-start hook injects the orientation regardless, but AGENTS.md remains the fallback and the source of the Team Context in Use output contract.)
- **Interpolating user input into Python/shell source strings** — pass paths through the environment (`os.environ`) instead; string interpolation of `$ABSOLUTE_PATH` into a Python one-liner is a command-injection vector.
- **Cloning a non-`https://` URL in Mode 1** — reject `file://`/`ssh://`/other schemes; cloned content is read by agents later, so only clone trusted repos.
- **Skipping the MCP config install** — `.mcp.json` servers stay unconfigured; the project won't have access to team-declared MCP servers.
- **Accepting shell metacharacters in paths or team names** — validate before interpolating into `mkdir`/`git commit`/heredocs (see Input Validation).
- **Treating user decline as an error** — declining setup is a valid outcome; exit cleanly, tell `team-boot` the user declined, and offer the `team_ai_directives: null` opt-out marker (build mode only).
- **Writing the opt-out marker in plan/read-only mode** — a persistent opt-out requires a write; in plan mode the decline is session-scoped and setup defers instead.

## Verification

- [ ] The team AI directives directory exists at the configured path.
- [ ] `{TEAM_AI_DIRECTIVES}/context_modules/constitution.md` exists.
- [ ] `{TEAM_AI_DIRECTIVES}/context_modules/rules/` exists.
- [ ] `{TEAM_AI_DIRECTIVES}/context_modules/personas/` exists.
- [ ] `{TEAM_AI_DIRECTIVES}/context_modules/examples/` exists.
- [ ] `{TEAM_AI_DIRECTIVES}/CDR.md` exists.
- [ ] `{TEAM_AI_DIRECTIVES}/.skills.json` exists and is valid JSON.
- [ ] `.adlc/init-options.json` contains a `team_ai_directives` field with the absolute path.
- [ ] Project-level `AGENTS.md` exists and contains the `<!-- TEAM_AI_DIRECTIVES START -->` managed section with the event-hook awareness note, fallback `team-boot` invocation, and the Team Context in Use output contract.
- [ ] (Mode 3 only) `git rev-parse --is-inside-work-tree` succeeds inside `{TEAM_AI_DIRECTIVES}`.
- [ ] Running `team-verify` (Phase 0 of team-repair) passes all 7 checks.
- [ ] All user-supplied paths/URLs/team names passed Input Validation (no shell metacharacters; clone URL is `https://`).
- [ ] Mode 2 wrote `team_ai_directives` via the environment (no `$ABSOLUTE_PATH` interpolation into Python source).
- [ ] If `{TEAM_AI_DIRECTIVES}/.mcp.json` exists, any declared `mcpServers` were successfully merged into the project's config, and unresolved env vars were highlighted.
- [ ] (Model-invoked by `team-boot`) a user decline exited cleanly without running any mode; the persistent opt-out was offered, and `team_ai_directives: null` was written only in build mode.

## Configuration

- `TEAM_AI_DIRECTIVES` — Path to the team AI directives (overrides `.adlc/init-options.json`).
- `.adlc/init-options.json` — Project-level config file with `team_ai_directives` field.
- Default fallback: `team-ai-directives/` relative to project root.
- `team-helpers.sh` / `team-helpers.ps1` — Shared scripts used for scaffolding and path resolution.

## 12-Factor Alignment

Factor XI (Directives as Code) — establishes a version-controlled team directives repository.

#!/usr/bin/env bash
# team-helpers.sh — Shared utilities for team-* skills
# 
# Flags:
#   --json              Output path info as JSON (default: key=value)
#   --scaffold [DIR]    Create a fresh 11-file team AI directives scaffold at DIR
#   --agents-only DIR   Create only AGENTS.md at DIR (for repair use)
#   --inject-agents [DIR]  Inject team-boot directive into project-level AGENTS.md at DIR
#   --name NAME         Team name for scaffold (default: "My Team")
set -euo pipefail

###############################################################################
# 1. PATH RESOLUTION
###############################################################################

resolve_paths() {
  PROJECT_ROOT="${PROJECT_ROOT:-$([[ -d ".adlc" ]] && pwd || git rev-parse --show-toplevel 2>/dev/null || pwd)}"
  BRANCH="${BRANCH:-$(git branch --show-current 2>/dev/null || echo 'unknown')}"
  TEAM_AI_DIRECTIVES=""

  # 1. Check TEAM_AI_DIRECTIVES env var (highest priority)
  if [[ -n "${TEAM_AI_DIRECTIVES:-}" ]]; then
    TEAM_AI_DIRECTIVES="$TEAM_AI_DIRECTIVES"
  fi

  # 2. Check .adlc/init-options.json
  if [[ -z "$TEAM_AI_DIRECTIVES" ]]; then
    INIT_OPTIONS="${PROJECT_ROOT}/.adlc/init-options.json"
    if [[ -f "$INIT_OPTIONS" ]]; then
      TEAM_AI_DIRECTIVES=$(python3 -c "
import json, sys
try:
    with open('$INIT_OPTIONS') as f:
        print(json.load(f).get('team_ai_directives', ''))
except Exception:
    print('')
" 2>/dev/null || true)
    fi
  fi

  # 3. Fallback to default path
  if [[ -z "$TEAM_AI_DIRECTIVES" ]]; then
    TEAM_AI_DIRECTIVES="${PROJECT_ROOT}/team-ai-directives"
  fi

  echo "PROJECT_ROOT=$PROJECT_ROOT"
  echo "TEAM_AI_DIRECTIVES=$TEAM_AI_DIRECTIVES"
  echo "BRANCH=$BRANCH"
}

output_json() {
  printf '{"REPO_ROOT": "%s", "TEAM_AI_DIRECTIVES": "%s", "BRANCH": "%s"}\n' \
    "$PROJECT_ROOT" "$TEAM_AI_DIRECTIVES" "$BRANCH"
}

###############################################################################
# 2. TEAM AI DIRECTIVES STRUCTURE VALIDATION
###############################################################################

validate_team_ai_directives() {
  local dir="$1"
  local missing=0

  for required in \
    "context_modules/constitution.md" \
    "context_modules/rules" \
    "context_modules/personas" \
    "context_modules/examples" \
    "CDR.md" \
    ".skills.json"; do
    if [[ ! -e "${dir}/${required}" ]]; then
      echo "MISSING: ${required}"
      missing=$((missing + 1))
    fi
  done

  return "$missing"
}

###############################################################################
# 3. SCAFFOLD
###############################################################################

scaffold_team_ai_directives() {
  local dest="$1"
  local team_name="${2:-My Team}"
  local today
  today=$(date +%Y-%m-%d)

  if [[ -d "$dest" && -n "$(ls -A "$dest" 2>/dev/null)" ]]; then
    echo "ERROR: Destination '$dest' already exists and is not empty." >&2
    exit 1
  fi

  mkdir -p "${dest}/context_modules/rules"
  mkdir -p "${dest}/context_modules/personas"
  mkdir -p "${dest}/context_modules/examples"
  mkdir -p "${dest}/skills"

  cat > "${dest}/README.md" << README
# ${team_name} Team AI Directives

Team AI directives repository for ${team_name}.

## Getting Started

1. Wire this directives repository into a project:
   \`\`\`
   /team-setup
   \`\`\`
   Choose "Point to existing local path" and select this directory.

2. Add context modules to \`context_modules/\` (rules, personas, examples).

3. Add skills to \`skills/\` and register them in \`.skills.json\`.

4. Update \`CDR.md\` as context modules are approved.

See [ADLC Team Skills](https://github.com/tikalk/adlc-team-skills) for full documentation.
README

  cat > "${dest}/AGENTS.md" << 'AGENTS'
# Agent Instructions

## Structure

- `context_modules/constitution.md` — Team constitution
- `context_modules/rules/` — Team rules and workflows
- `context_modules/personas/` — Team personas
- `context_modules/examples/` — Team examples
- `skills/` — Team skills
- `evals/` — Directive compliance goldensets (pass/fail cases)
- `CDR.md` — Context Directive Records

## Loading Order

1. Load constitution.md first
2. Load relevant rules for the current task
3. Load relevant personas for the current task
4. Load relevant examples for the current task

## Using Skills

Skills are located in the `skills/` directory. Browse available skills using team-skills and install them as needed.

## CDR.md

The CDR.md file tracks approved context contributions. Update it when adding new context modules.
AGENTS

  cat > "${dest}/CDR.md" << CDR
# Context Directive Records

Context Directive Records (CDRs) track decisions about contributing context modules (rules, personas, examples, skills) to team-ai-directives.

## CDR Index

| ID | Target Module | Type | Status | Created | Verified | Age | Descriptor |
|----|---------------|------|--------|---------|----------|-----|------------|

**Stats**: 0 entries | Last Updated: ${today}
CDR

  cat > "${dest}/.skills.json" << 'SKILLSJSON'
{
  "version": "2.0.0",
  "source": "team-ai-directives",
  "description": "Team skills manifest. The `default` list contains skill names that are auto-installed during project setup. The `external` map contains on-demand skills fetched by URL. The `blocked` list contains skills that must never be installed.",
  "default": [],
  "external": {},
  "blocked": [],
  "policy": {
    "auto_install_default": true,
    "enforce_blocked": true,
    "allow_project_override": true
  }
}
SKILLSJSON

  cat > "${dest}/.mcp.json.example" << 'MCPJSON'
{
  "mcpServers": {}
}
MCPJSON

  cat > "${dest}/context_modules/constitution.md" << CONSTITUTION
---
type: Constitution
title: "${team_name} Constitution"
description: "Team-wide principles and governance"
resource: ./context_modules/constitution.md
tags: [constitution]
generated: { by: agent:team-setup, at: ${today}T00:00:00Z }
id: constitution
cdr_ref: null
created: ${today}
verified:
  - { by: agent:team-setup, at: ${today}T00:00:00Z }
status: stable
stale_after: 180d
---

# ${team_name} Constitution

No team-wide principles defined yet. Add principles as they are established.
CONSTITUTION

  cat > "${dest}/context_modules/index.md" << 'INDEXTOP'
---
okf_version: "0.2"
---

# Context Modules

* [Rules](rules/index.md) - Team rules and workflows
* [Personas](personas/index.md) - Team personas
* [Examples](examples/index.md) - Team examples
INDEXTOP

  cat > "${dest}/context_modules/log.md" << 'LOGTOP'
# Context Modules Update Log
LOGTOP

  cat > "${dest}/context_modules/rules/index.md" << 'INDEXRULES'
# Rules

No rules defined yet. Use /team-learn to create rules via CDRs.
INDEXRULES

  cat > "${dest}/context_modules/rules/log.md" << 'LOGRULES'
# Rules Update Log
LOGRULES

  cat > "${dest}/context_modules/personas/index.md" << 'INDEXPERS'
# Personas

No personas defined yet. Use /team-learn to create personas via CDRs.
INDEXPERS

  cat > "${dest}/context_modules/personas/log.md" << 'LOGPERS'
# Personas Update Log
LOGPERS

  cat > "${dest}/context_modules/examples/index.md" << 'INDEXEX'
# Examples

No examples defined yet. Use /team-learn to create examples via CDRs.
INDEXEX

  cat > "${dest}/context_modules/examples/log.md" << 'LOGEX'
# Examples Update Log
LOGEX

  cat > "${dest}/CDR.md" << 'CDRDERIVED'
# Context Directive Records (Derived Index)

> ⚠️ Auto-generated by `/team-repair`. Do not edit manually.
> Source of truth: `context_modules/*/index.md` + module frontmatter.
> Decision lifecycle (Accepted/Rejected) lives in the `adlc` orphan branch `drafts/cdr/`.

## CDR Index

| ID | Path | Type | Description | Generated | Verified | Age | Status |
|----|------|------|-------------|-----------|----------|-----|--------|

**Stats**: 0 entries | Last Updated: PLACEHOLDER
CDRDERIVED

  touch "${dest}/context_modules/rules/.gitkeep"
  touch "${dest}/context_modules/personas/.gitkeep"
  touch "${dest}/context_modules/examples/.gitkeep"
  touch "${dest}/skills/.gitkeep"

  echo "Scaffolded team-ai-directives at ${dest}"
  echo "Team name: ${team_name}"
  echo "Files created: 14"

  validate_team_ai_directives "$dest" || true
}

scaffold_agents_only() {
  local dest="$1"
  mkdir -p "$dest"

  cat > "${dest}/AGENTS.md" << 'AGENTS'
# Agent Instructions

## Structure

- `context_modules/constitution.md` — Team constitution
- `context_modules/rules/` — Team rules and workflows
- `context_modules/personas/` — Team personas
- `context_modules/examples/` — Team examples
- `skills/` — Team skills
- `reports/sessions/` — Published session summaries (from `/team-learn`, on `adlc` branch)
- `CDR.md` — Context Directive Records

## Loading Order

1. Load constitution.md first
2. Load relevant rules for the current task
3. Load relevant personas for the current task
4. Load relevant examples for the current task

## Using Skills

Skills are located in the `skills/` directory. Browse available skills using team-skills and install them as needed.

## CDR.md

The CDR.md file tracks approved context contributions. Update it when adding new context modules.
AGENTS

  echo "Created AGENTS.md at ${dest}"
}

###############################################################################
# 4. INJECT PROJECT-LEVEL AGENTS.md DIRECTIVE
###############################################################################

inject_project_agents() {
  local project_root="${1:-.}"
  local team_directive="${2:-}"

  # Resolve team_ai_directives if not provided
  if [[ -z "$team_directive" ]]; then
    local init_options="${project_root}/.adlc/init-options.json"
    if [[ -f "$init_options" ]]; then
      team_directive=$(python3 -c "
import json, sys
try:
    with open('$init_options') as f:
        print(json.load(f).get('team_ai_directives', ''))
except Exception:
    print('')
" 2>/dev/null || true)
    fi
  fi

  # Fallback to env var
  if [[ -z "$team_directive" ]] && [[ -n "${TEAM_AI_DIRECTIVES:-}" ]]; then
    team_directive="$TEAM_AI_DIRECTIVES"
  fi

  # Fallback to default path
  if [[ -z "$team_directive" ]]; then
    team_directive="${project_root}/team-ai-directives"
  fi

  local agents_file="${project_root}/AGENTS.md"
  local marker_start="<!-- TEAM_AI_DIRECTIVES START -->"
  local marker_end="<!-- TEAM_AI_DIRECTIVES END -->"

  # Build the managed section
  local section
  section=$(cat <<SECTION
${marker_start}
# Team AI Directives

This project is bound by the team AI directives repository at \`${team_directive}\`.

team-boot runs automatically at session start via the event hook (for agents with event support), injecting a lean orientation into the first user message with the team constitution, CDR index, Class Boots catalog, skills registry, and MCP servers.

If the team AI directives context is NOT in your system prompt or first user message (agent without event support), invoke the \`team-boot\` skill before responding to any task or question.

If team AI directives are unconfigured, invoke the \`team-setup\` skill.

Invoke the matching class boot when a task or decision matches a row:

## Class Boots

| Boot | Injects | Invoke When | Capture Via |
|--|--|--|--|
| architect-boot | ADR index (.adlc/memory/adr/) | architecture work; tech-stack/pattern choice | /architect-specify |
| product-boot | PDR index (.adlc/memory/pdr/) | product/feature scope, personas, monetization | /product-specify |
| change-boot | ChDR index (.adlc/memory/chdr.md) | change-history rationale, reverts, issue-linked commits | /change-init |
| team-boot | CDR module bodies (team-ai-directives) | CDR descriptor match; reusable team pattern | /team-learn |
| tech-radar-boot | Tikal Tech Radar context | choosing/evaluating technology | radar context + /architect-specify |

Each class boot emits its class context section and its own searched line (_Searched N records, K matched._).

**Every response MUST include** a Team Context in Use section before the task answer:

## Team Context in Use

| ID | Name | Type | Rel |
|--|--|--|--|
| CDR-YYYY-NNN | <name> | <type> | <relevance> |

Plus: \`_Searched N CDRs, M skills, J matched._\` — **J MUST equal the number of rows in your table; if no CDRs/skills genuinely match, show an empty table with 0 matched (do not copy a hard-coded CDR or inflate the count).**

## Decision Capture

Detect decisions as they emerge; full detection and capture guidance lives in the matching class boot:

- Tech stack / pattern choice → ADR → /architect-specify (pull tech-radar-boot context first for tech selection)
- Feature scope / persona / monetization → PDR → /product-specify
- Reusable team rule / pattern → CDR → /team-learn
- Revert/hotfix rationale / issue-linked commit → ChDR → /change-init

Maintain a running Session Decision Ledger in every response (after the Team Context in Use table):

| Decision | Type | Captured? | Skill |
|----------|------|-----------|-------|
| _none yet_ | — | — | — |

_Unrecorded: N pending._

At session end, prompt to invoke the capture skills for any unrecorded decisions. Only suggest capture when genuinely warranted.
${marker_end}
SECTION
)

  # Create AGENTS.md if it doesn't exist, or update the managed section
  python3 - "$agents_file" "$marker_start" "$marker_end" "$section" <<'PY'
import os, sys

agents_path, start, end, section_content = sys.argv[1:5]

if os.path.exists(agents_path):
    with open(agents_path, "r", encoding="utf-8") as f:
        content = f.read()
else:
    content = ""

# Check if markers already exist
s_idx = content.find(start)
e_idx = content.find(end)

if s_idx != -1 and e_idx != -1 and s_idx < e_idx:
    # Replace existing managed section
    new_content = content[:s_idx] + section_content + content[e_idx + len(end):]
    if new_content.endswith("\n"):
        new_content += "\n"
    elif not new_content.endswith("\n\n"):
        new_content += "\n"
    with open(agents_path, "w", encoding="utf-8") as f:
        f.write(new_content)
    print(f"Updated team AI directives section in {agents_path}")
else:
    # Append managed section
    if content and not content.endswith("\n"):
        content += "\n"
    if content and not content.endswith("\n\n"):
        content += "\n"
    content += section_content + "\n"
    with open(agents_path, "w", encoding="utf-8") as f:
        f.write(content)
    print(f"Injected team AI directives section into {agents_path}")
PY
}

###############################################################################
# MAIN
###############################################################################

main() {
  if [[ "$#" -eq 0 ]]; then
    resolve_paths
    return
  fi

  local has_json=false
  local has_scaffold=false
  local has_agents_only=false
  local has_inject_agents=false
  local scaffold_dest=""
  local agents_only_dest=""
  local inject_dest=""
  local team_name="My Team"
  local parsing_scaffold=false
  local parsing_agents=false
  local parsing_name=false
  local parsing_inject=false

  for arg in "$@"; do
    if [[ "$arg" == "--json" || "$arg" == "-Json" ]]; then
      has_json=true
      continue
    fi
    if [[ "$arg" == "--help" || "$arg" == "-h" ]]; then
      echo "Usage: team-helpers.sh [--json] [--scaffold DIR] [--agents-only DIR] [--inject-agents [DIR]] [--name NAME]"
      exit 0
    fi
    if [[ "$arg" == "--scaffold" ]]; then
      has_scaffold=true
      parsing_scaffold=true
      parsing_agents=false
      parsing_name=false
      parsing_inject=false
      continue
    fi
    if [[ "$arg" == "--agents-only" ]]; then
      has_agents_only=true
      parsing_agents=true
      parsing_scaffold=false
      parsing_name=false
      parsing_inject=false
      continue
    fi
    if [[ "$arg" == "--inject-agents" ]]; then
      has_inject_agents=true
      parsing_inject=true
      parsing_scaffold=false
      parsing_agents=false
      parsing_name=false
      continue
    fi
    if [[ "$arg" == "--name" ]]; then
      parsing_name=true
      parsing_scaffold=false
      parsing_agents=false
      parsing_inject=false
      continue
    fi
    if $parsing_scaffold && [[ -n "$arg" ]]; then
      scaffold_dest="$arg"
      parsing_scaffold=false
      continue
    fi
    if $parsing_agents && [[ -n "$arg" ]]; then
      agents_only_dest="$arg"
      parsing_agents=false
      continue
    fi
    if $parsing_inject && [[ -n "$arg" ]]; then
      inject_dest="$arg"
      parsing_inject=false
      continue
    fi
    if $parsing_name && [[ -n "$arg" ]]; then
      team_name="$arg"
      parsing_name=false
      continue
    fi
  done

  if $has_scaffold; then
    if [[ -z "$scaffold_dest" ]]; then
      echo "ERROR: --scaffold requires a destination directory argument" >&2
      exit 1
    fi
    scaffold_team_ai_directives "$scaffold_dest" "$team_name"
    return
  fi

  if $has_agents_only; then
    if [[ -z "$agents_only_dest" ]]; then
      echo "ERROR: --agents-only requires a destination directory argument" >&2
      exit 1
    fi
    scaffold_agents_only "$agents_only_dest"
    return
  fi

  if $has_inject_agents; then
    local project_root="${inject_dest:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
    inject_project_agents "$project_root"
    return
  fi

  # Default: resolve paths
  resolve_paths > /dev/null
  if $has_json; then
    output_json
  else
    resolve_paths
  fi
}

main "$@"