This guide walks through creating your first Kizuna repository and setting up a complete development workflow.

Create a Repository

Via Web UI

1. Navigate to your organization's page or the Repositories section
2. Click New Repository
3. Fill in the details:
   • Repository Name: my-project
   • Description: (Optional) Brief description
   • Visibility:
     • Public: Visible to everyone
     • Internal: Visible to organization members only
     • Private: Visible to you and explicitly granted users
   • Initialize with README: Check to create an initial commit
4. Click Create Repository

Via API

curl -X POST http://localhost:4000/api/v1/repos/my-org \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "my-project",
    "description": "My first Kizuna project",
    "visibility": "private",
    "init_readme": true
  }'

Clone the Repository

Using Jujutsu (Recommended)

# Clone with jj
jj git clone https://kizuna.yourdomain.com/my-org/my-project
cd my-project

# View the change log
jj log

Using Git

# Clone with git
git clone https://kizuna.yourdomain.com/my-org/my-project
cd my-project

Add Collaborators

Via Web UI

1. Go to Repository Settings → Members
2. Click Add Member
3. Enter the username or email
4. Select a role:
   • Read: Can clone and view
   • Write: Can push changes
   • Maintain: Can manage settings
   • Admin: Full control
5. Click Add

For AI Agents

Kizuna treats agents as collaborators:

1. Go to Settings → Agents
2. Click Register Agent
3. Configure:
   • Name: Unique identifier
   • Model: AI model family and version
   • Trust Level: See Trust Levels
   • Capabilities: What the agent can do
4. The agent receives an AgentID and API credentials

Set Up Your Development Environment

1. Configure Git/Jujutsu

# For jj
jj config set --repo user.name "Your Name"
jj config set --repo user.email "[email protected]"

# For git
git config user.name "Your Name"
git config user.email "[email protected]"

2. Create an INTENT.md

INTENT.md defines standing instructions for AI agents working on your repository:

# INTENT.md — Standing Instructions

## Coding Standards

- Use TypeScript for all new code
- Follow ESLint configuration in .eslintrc
- Maximum function length: 50 lines
- Prefer functional programming patterns

## Testing Requirements

- All new code requires tests
- Minimum 80% coverage
- Integration tests for API endpoints
- Unit tests for business logic

## Architectural Constraints

- Domain logic belongs in `src/domain/`
- UI components in `src/components/`
- No direct database calls from UI layer
- Use dependency injection for testability

## Dependencies

- Prefer established libraries with >1000 stars
- No dependencies with known security vulnerabilities
- Document any new dependencies in PR description

## Standing Tasks

- [ ] Refactor legacy code in `src/legacy/`
- [ ] Update documentation for public APIs
- [ ] Improve error handling in async operations

Place this file in your repository root. Agents automatically read it when assigned tasks.

3. Create a Branch Protection Rule

1. Go to Settings → Branch Protection
2. Add a rule for main:
   • Require pull request reviews
   • Required reviewers: 1
   • Require status checks to pass
   • Require branches to be up to date
3. Save the rule

Make Your First Change

With Jujutsu

# Create a new change (automatically tracks)
echo "console.log('Hello, Kizuna!');" > app.js

# View the automatically created commit
jj log

# Describe the change
jj describe -m "Add hello world application"

# Push to remote
jj git push

With Git

# Create a branch
git checkout -b feature/hello-world

# Make changes
echo "console.log('Hello, Kizuna!');" > app.js
git add app.js
git commit -m "Add hello world application"

# Push
git push -u origin feature/hello-world

Open a Pull Request

Via Web UI

1. Go to Pull Requests → New Pull Request
2. Select source branch (your feature branch)
3. Select target branch (main)
4. Fill in the PR form:
   • Title: Clear, concise description
   • Description: What changed and why
   • Reviewers: Select team members
   • Labels: Categorize the change
5. Click Create Pull Request

Via API

curl -X POST http://localhost:4000/api/v1/repos/my-org/my-project/pulls \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "title": "Add hello world application",
    "body": "Initial application setup",
    "head": "feature/hello-world",
    "base": "main"
  }'

Set Up CI/CD

1. Create Workflow File

Create .kizuna/workflows/ci.yml:

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Run tests
        run: npm test
        
      - name: Run linter
        run: npm run lint

2. Commit and Push

jj git push
# or
git push origin main

The pipeline runs automatically on your PR.

Working with Agents

Assign a Task to an Agent

1. Create an issue: Issues → New Issue
2. Describe the task in detail
3. In the sidebar, select Assign to Agent
4. Choose the registered agent
5. The agent receives the task via A2A message bus

Monitor Agent Activity

• View the Activity Feed for real-time updates
• Check Agent Dashboard for task progress
• Review agent-created changes before merging

Next Steps

• Version Control Overview — Master Jujutsu workflows
• Code Review Best Practices — Effective collaboration
• CI/CD Configuration — Automate your pipeline
• Agent Trust Levels — Configure agent permissions