saltbo__agent-kanban/CONTRIBUTING.md

Contributing

Thanks for your interest in Agent Kanban! Here's how to get involved.

Getting Started

1. Fork the repo and clone it locally
2. Install dependencies: pnpm install
3. Run migrations: pnpm db:migrate
4. Start dev server: pnpm dev
5. Run the exact tests selected for your changed behaviour

Making Changes

• Create a feature branch from main
• Keep changes focused — one concern per PR
• Change or add the scenario in spec/*.feature first
• Add [spec: capability/scenario] to the cheapest proving test
• Run pnpm lint:spec and the exact changed test cases before submitting

Code Style

• TypeScript throughout
• Thin repo layer for data access — no raw SQL in route handlers
• Centralized error handling via HTTPException
• Short functions (< 30 lines), small files (< 300 lines)
• Name things clearly — if it needs a comment to explain what, rename it

Commit Messages

Use Conventional Commits:

feat(api): add task dependency cycle detection
fix(cli): handle missing config file on first run
refactor(web): extract activity log into standalone component

Database Migrations

If your change modifies the D1 schema:

1. Create a new SQL file in migrations/
2. Name it NNNN_description.sql (sequential number)
3. Include both the schema change and any data backfill
4. Test with pnpm db:migrate

Reporting Issues

Open an issue with:

• What you expected vs. what happened
• Steps to reproduce
• Environment (OS, Node version, browser)

License

By contributing, you agree that your contributions will be licensed under the FSL-1.1-ALv2 license.