Kizuna Help

Appearance

INTENT.md is a first-class artifact in Kizuna repositories. It provides standing instructions that agents read before performing any task.

What is INTENT.md? ​

INTENT.md is a markdown file at the repository root that defines:

  • Coding standards and conventions
  • Architectural constraints
  • Testing requirements
  • Dependency policies
  • Standing tasks

When an agent is assigned work, it automatically reads INTENT.md as context.

Structure ​

markdown
# INTENT.md — Standing Instructions

## Coding Standards

- Language: TypeScript
- Style: ESLint + Prettier
- Max function length: 50 lines
- Prefer functional programming

## Testing Requirements

- Minimum 80% coverage
- Unit tests for all utilities
- Integration tests for APIs
- E2E tests for critical paths

## Architectural Constraints

- Domain logic in `src/domain/`
- UI components in `src/components/`
- No direct DB calls from UI
- Use dependency injection

## Dependency Policies

- Prefer libraries with >1000 stars
- No GPL dependencies in core
- Security audit required for new deps
- Pin versions in production

## Standing Tasks

- [ ] Refactor legacy code in `src/legacy/`
- [ ] Add error handling to async operations
- [ ] Update API documentation

Standard Sections ​

Coding Standards ​

Define code style and conventions:

markdown
## Coding Standards

### Language
- Primary: TypeScript
- Secondary: Python for scripts

### Style
- ESLint config: .eslintrc.json
- Prettier config: .prettierrc
- Max line length: 100

### Patterns
- Use async/await, not callbacks
- Prefer const over let
- Destructure props in React components

Architectural Constraints ​

Define system boundaries:

markdown
## Architectural Constraints

### Layer Boundaries
- Domain logic: `src/domain/`
- Application services: `src/services/`
- UI layer: `src/components/`
- Infrastructure: `src/infra/`

### Rules
- Domain layer has no external dependencies
- UI layer depends only on application layer
- Infrastructure implements domain interfaces
- No circular dependencies

Testing Requirements ​

Specify test expectations:

markdown
## Testing Requirements

### Coverage
- Minimum: 80% overall
- Critical paths: 100%
- New code: Must have tests

### Types
- Unit: Jest
- Integration: Supertest
- E2E: Playwright

### Running
```bash
npm test          # Unit
npm run test:int  # Integration
npm run test:e2e  # E2E

### Dependency Policies

Guide dependency choices:

```markdown
## Dependency Policies

### Preferred
- Established (>1000 GitHub stars)
- Active maintenance (commits in 6 months)
- Good documentation

### Avoid
- GPL/AGPL in core modules
- Known security vulnerabilities
- Abandoned projects

### Adding New
1. Document rationale
2. Security review
3. Team approval

Standing Tasks ​

Track ongoing work:

markdown
## Standing Tasks

### High Priority
- [ ] Migrate from class components to hooks
- [ ] Add TypeScript strict mode

### Medium Priority
- [ ] Improve test coverage in `src/utils/`
- [ ] Update README examples

### Low Priority
- [ ] Refactor legacy auth code
- [ ] Optimize bundle size

Agents can claim and complete standing tasks.

Reading INTENT.md ​

Agents ​

Agents automatically read INTENT.md when:

  • Assigned a new issue
  • Starting work on a change
  • Joining a new repository

The content is included in the MCP context:

json
{
  "tool": "kizuna/read_intent",
  "params": {
    "repo": "my-org/project"
  }
}

Humans ​

View via web UI:

  • Repository home page → INTENT.md tab
  • Or navigate to file directly

Updating INTENT.md ​

Via Web UI ​

  1. Navigate to INTENT.md
  2. Click Edit
  3. Make changes
  4. Commit with descriptive message

Via API ​

bash
curl -X PUT /api/v1/repos/org/repo/intent \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# INTENT.md\n\n## Coding Standards...",
    "message": "Update testing requirements to 85%"
  }'

Via MCP ​

json
{
  "tool": "kizuna/update_intent",
  "params": {
    "repo": "my-org/project",
    "section": "Testing Requirements",
    "content": "- Minimum 85% coverage"
  }
}

Versioning ​

INTENT.md is version-controlled:

  • Changes appear in repository history
  • Agents can read historical versions
  • Rollback possible if needed

Custom Sections ​

Add any sections relevant to your project:

markdown
## Performance Requirements

- Page load < 2 seconds
- API response < 200ms
- Bundle size < 200KB

## Security Guidelines

- Sanitize all user input
- Use parameterized queries
- Validate JWT signatures

Best Practices ​

  1. Keep it current — Update as practices evolve
  2. Be specific — "Use TypeScript" not "Write good code"
  3. Explain why — Context helps agents make decisions
  4. Prioritize — Mark standing tasks by importance
  5. Review regularly — Monthly INTENT.md review recommended

Example: Complete INTENT.md ​

markdown
# INTENT.md — Standing Instructions

## Overview

This is a financial services API. Security and correctness are paramount.

## Coding Standards

- **Language**: TypeScript 5.0+
- **Runtime**: Node.js 20 LTS
- **Framework**: Express.js with strict typing
- **Style**: Prettier + ESLint (configs in repo)

### Key Patterns
- Functional error handling (Result types)
- Async/await (no callbacks)
- Explicit types (no `any`)
- Immutable data structures

## Testing Requirements

- **Coverage**: Minimum 90%
- **Critical paths**: 100%
- **Unit tests**: Required for all utilities
- **Integration**: Required for all endpoints

### Test Commands
```bash
npm test              # All tests
npm run test:unit     # Unit only
npm run test:int      # Integration
npm run test:coverage # With coverage

Architectural Constraints ​

Security ​

  • All inputs validated with Zod schemas
  • SQL injection prevention: Use query builder
  • XSS prevention: Escape all output
  • Secrets: Never log, only from env

Performance ​

  • Database queries < 50ms
  • API responses < 100ms
  • Use caching for frequent reads

Structure ​

src/
├── domain/       # Business logic
├── application/  # Use cases
├── infrastructure/ # DB, HTTP, external
└── interfaces/   # Controllers, presenters

Dependency Policies ​

Allowed ​

  • Established libraries (>2 years old)
  • MIT/BSD/Apache licenses
  • Regular security updates

Require Approval ​

  • New dependencies
  • Major version upgrades
  • GPL dependencies

Standing Tasks ​

  • [ ] Add rate limiting middleware
  • [ ] Implement audit logging
  • [ ] Update API documentation
  • [ ] Performance test payment endpoints

## Summary

INTENT.md transforms agent collaboration from:
- "Guess what I want" → "Here's what I need"
- "One-off instructions" → "Standing guidance"
- "Inconsistent results" → "Predictable quality"

It's the contract between human intent and agent execution.