This tutorial guides you through setting up Kizuna for a development team — from organization configuration to establishing a review workflow that works.

Prerequisites

• A Kizuna account with admin permissions
• At least one other team member to invite
• A repository to configure (see Onboarding Tutorial)

Step 1: Configure Your Organization

Set Organization Defaults

1. Navigate to your organization page
2. Click Settings
3. Configure:
   • Default Repository Visibility: Internal (visible to org members only)
   • Default Branch: main
   • Member Permissions: Set the base permission level for new members

Create Teams

Teams let you manage permissions for groups of people:

1. Go to Organization Settings > Teams
2. Click New Team
3. Create teams based on your structure:

Team	Permission	Purpose
engineering	Write	All engineers — can push to repos
leads	Maintain	Tech leads — can manage settings
devops	Admin	DevOps — full access for CI/CD setup
contractors	Read	External contractors — read-only

4. Add members to each team

Step 2: Invite Team Members

Via Web UI

1. Go to Organization Settings > Members
2. Click Invite Member
3. Enter their email or Kizuna username
4. Assign them to one or more teams
5. Click Send Invitation

Via API (Bulk Invite)

# Invite multiple members programmatically
for email in alice@acme.com bob@acme.com carol@acme.com; do
  curl -X POST https://kizuna.yourcompany.com/api/v1/orgs/my-team/members \
    -H "Authorization: Bearer $ADMIN_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"email\": \"$email\", \"role\": \"member\", \"team\": \"engineering\"}"
done

Step 3: Set Up Branch Protection

Protect your main branch from accidental or unauthorized changes.

Configure Protection Rules

1. Navigate to your repository > Settings > Branch Protection
2. Click Add Rule
3. Set the branch pattern: main
4. Enable these protections:

Rule	Recommended Setting	Purpose
Require pull request	Yes	No direct pushes to main
Required reviewers	1-2	At least one approval needed
Require status checks	Yes	CI must pass before merge
Require up-to-date branch	Yes	Branch must be rebased
Include administrators	Yes	Rules apply to everyone

5. Click Save

Add Required Status Checks

After your CI pipeline runs at least once, you can require specific checks:

1. In the branch protection rule, under Required Status Checks
2. Search and select: ci / test, ci / lint, etc.
3. These must pass before any PR can be merged

Step 4: Create a CODEOWNERS File

Automatically assign reviewers based on file paths:

# Create CODEOWNERS in the repository root
cat > CODEOWNERS << 'EOF'
# Default reviewers for everything
* @my-team/leads

# Frontend — frontend team reviews
src/components/** @alice @bob
src/pages/** @alice @bob

# Backend — backend team reviews
src/api/** @carol @dave
src/models/** @carol @dave

# Infrastructure — devops reviews
.kizuna/workflows/** @my-team/devops
Dockerfile @my-team/devops
k8s/** @my-team/devops

# Documentation — anyone can review
docs/** @my-team/engineering
EOF

Commit and push this file. Kizuna will automatically assign reviewers when PRs touch matching paths.

Step 5: Set Up INTENT.md

Create standing instructions for AI agents working on your repository:

cat > INTENT.md << 'EOF'
# INTENT.md — Standing Instructions for AI Agents

## Project Context
This is an internal API service built with Node.js and TypeScript.

## Coding Standards
- TypeScript strict mode for all new files
- ESLint + Prettier configuration in the repo
- Maximum 50 lines per function
- Prefer pure functions and immutability

## Testing
- All new code requires tests (Jest)
- Minimum 80% line coverage
- Integration tests for API endpoints
- Unit tests for business logic

## Architecture
- Domain logic in `src/domain/`
- API routes in `src/api/`
- Shared types in `src/types/`
- No direct database access from route handlers

## PR Requirements
- Descriptive title (imperative mood)
- Link to issue if applicable
- Update relevant documentation
- No console.log in production code
EOF

Step 6: Establish a Workflow

Recommended PR Workflow

Communicate this workflow to your team:

1. Create a branch from main for each piece of work
2. Make changes and push to the branch
3. Open a PR with:
   • Clear title describing the change
   • Description with context and testing notes
   • Link to the related issue
4. Get reviews — CODEOWNERS assigns reviewers automatically
5. Address feedback — push fixes to the same branch
6. CI must pass — all required checks green
7. Merge — squash merge for clean history (recommended)

Branch Naming Convention

Suggest a convention for your team:

feature/ISSUE-123-add-user-auth
fix/ISSUE-456-null-pointer-error
chore/update-dependencies
docs/api-endpoint-guide

Step 7: Configure Notifications

Webhooks for Team Chat

Send repository events to Slack, Discord, or other platforms:

1. Go to Repository Settings > Webhooks
2. Click Add Webhook
3. Configure:
   • URL: Your Slack/Discord webhook URL
   • Events: Select Pull Request, Push, Issue, Pipeline
   • Content Type: application/json
4. Click Save

Personal Notification Preferences

Each team member can configure their notifications:

1. Go to Personal Settings > Notifications
2. Choose notification level per repository:
   • All Activity — every event
   • Participating — only threads you're involved in
   • Mentions Only — only when @mentioned
   • None — muted

Step 8: Register a Team Agent (Optional)

Set up an AI agent for automated code review:

1. Go to Organization Settings > Agents
2. Click Register New Agent
3. Configure:
   • Name: code-reviewer
   • Model Family: claude
   • Model Version: 3.5-sonnet
   • Trust Level: 2 (Standard — can create PRs)
   • Capabilities: review, comment, suggest
4. Click Register
5. Assign the agent to repositories in Repository Settings > Agents

The agent will automatically review new PRs based on your INTENT.md instructions.

Team Checklist

Use this checklist to verify your setup:

• [ ] Organization created with appropriate visibility
• [ ] Teams created with correct permission levels
• [ ] All team members invited and assigned to teams
• [ ] Branch protection enabled on main
• [ ] Required status checks configured
• [ ] CODEOWNERS file committed
• [ ] INTENT.md created for agent instructions
• [ ] Webhook notifications configured for team chat
• [ ] CI/CD pipeline set up (see CI/CD Tutorial)
• [ ] SSH keys configured for all members

Next Steps

• Tutorial: CI/CD Setup — Automate your build pipeline
• Tutorial: Working with Agents — AI-assisted development
• Branch Protection Reference — Advanced protection rules
• CODEOWNERS Reference — Syntax and patterns