Team Setup

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:

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

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.

# 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

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 | Empty CDR index table | | 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 frontmatter) — fill via /team-constitution | | 7 | context_modules/index.md | OKF toplevel index linking sub-directories | | 8 | context_modules/rules/index.md | OKF progressive disclosure (rules) | | 9 | context_modules/rules/.gitkeep | Rules directory placeholder | | 10 | context_modules/personas/index.md | OKF progressive disclosure (personas) | | 11 | context_modules/personas/.gitkeep | Personas directory placeholder | | 12 | context_modules/examples/index.md | OKF progressive disclosure (examples) | | 13 | context_modules/examples/.gitkeep | Examples directory placeholder | | 14 | 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:

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:

# {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:

# 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

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

Create {DEST}/CDR.md:

# 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}

Create {DEST}/.skills.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:

{
  "mcpServers": {}
}

Create {DEST}/context_modules/constitution.md:

---
type: Constitution
title: "{TEAM_NAME} Constitution"
description: "Team-wide principles and governance"
resource: ./context_modules/constitution.md
tags: [constitution]
timestamp: {TODAY}T00:00:00Z
---

# {TEAM_NAME} Constitution

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

Create OKF-compliant index.md files for progressive disclosure:

Create {DEST}/context_modules/index.md:

# Context Modules

| Directory | Description |
|-----------|-------------|
| [rules/](rules/index.md) | Team rules and workflows |
| [personas/](personas/index.md) | Team personas |
| [examples/](examples/index.md) | Team examples |

Create {DEST}/context_modules/rules/index.md:

# Rules

No rules defined yet. Use `/levelup-specify` to create rules via CDRs.

Create {DEST}/context_modules/personas/index.md:

# Personas

No personas defined yet. Use `/levelup-specify` to create personas via CDRs.

Create {DEST}/context_modules/examples/index.md:

# Examples

No examples defined yet. Use `/levelup-specify` to create examples via CDRs.

Create gitkeep files:

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 /levelup-publish branch/commit/PR flow):

cd "{DEST}" && git init && git add -A && git commit -m "Initial team-ai-directives scaffold"

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

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 ```

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

1. Confirm: Ask the user to confirm before executing.

1. 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

1. Inject the project-level AGENTS.md directive so agents auto-invoke team-boot at session start:

# 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 ` and ` 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 | Relevance) listing genuinely matched CDRs/skills, followed by _Searched N CDR entries, 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.

1. 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

…

Source & license

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

• Author: tikalk
• Source: tikalk/adlc-team-skills
• License: MIT
• Homepage: https://github.com/tikalk/agentic-sdlc-12-factors

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