👻 Built for Kiroween Hackathon - Showcasing AI-assisted development with Kiro

Kaiord is an open-source toolkit for structured workout data.

It provides:

• @kaiord/core: a TypeScript library to read/write .fit, .tcx, .zwo and .krd (Kaiord) files.
• @kaiord/cli: a command-line tool to convert between formats.
• Workout SPA Editor: a web application to create and edit workout files visually.

• Visual Workout Editor - Create and edit workouts in your browser
• Unified JSON-based format .krd (Kaiord Representation Definition)
• Schema validation (AJV)
• Spec-driven development with Kiro
• Round-trip safe conversions between FIT / TCX / ZWO / KRD
• Clean architecture & fully typed API

• Sub-sport categorization: Detailed sport types (trail running, indoor cycling, lap swimming, etc.)
• Pool dimensions: Pool length and unit for swimming workouts

• Coaching notes: Instructional text for each step (max 256 characters)
• Swimming equipment: Fins, kickboard, paddles, pull buoy, snorkel

• Time & distance: Standard interval durations
• Calorie-based: Steps ending after burning specified calories
• Power-based: Steps ending based on power thresholds (watts)
• Heart rate conditionals: Steps ending based on HR thresholds (bpm)
• Repeat conditionals: Repeat blocks until time/distance/calories/HR/power targets reached

• Training Stress Score (TSS): The training_peaks_tss duration type is not yet implemented in the FIT converter. This is a TrainingPeaks-specific metric that requires additional mapping logic. Contributions welcome!

Comprehensive documentation is available in the /docs directory:

• Getting Started - Installation, basic usage, and quick examples for both library and CLI
• Architecture - Hexagonal architecture, ports & adapters pattern, and design principles
• Testing - Testing strategy, TDD workflow, and coverage requirements
• Deployment - CI/CD pipeline, GitHub Pages deployment, and npm publishing
• Contributing - Contribution guidelines, development workflow, and code standards
• KRD Format - Complete specification of the Kaiord Representation Definition format
• AI Agents - Guidance for AI-assisted development with Kiro and other tools

kaiord/
├─ packages/
│  ├─ core/                → library (schema + converters)
│  ├─ cli/                 → command-line interface
│  └─ workout-spa-editor/  → web application (https://pablo-albaladejo.github.io/kaiord)
├─ .kiro/   → steering docs, specs, hooks
├─ LICENSE
├─ README.md
└─ pnpm-workspace.yaml

Launch Workout Editor →

Create and edit workouts visually in your browser. No installation required.

pnpm install
pnpm -r build
pnpm -r test

# Example usage
pnpm kaiord --help

For detailed installation instructions and usage examples, see the Getting Started Guide.

Kaiord uses GitHub Actions for continuous integration and deployment:

• Automated Testing: Multi-version testing on Node.js 20.x and 22.x
• Code Quality: ESLint, Prettier, and TypeScript strict mode validation
• Release Automation: Changesets for version management and npm publishing
• Security: Weekly dependency vulnerability audits

For complete CI/CD documentation, deployment guides, and npm publishing instructions, see Deployment.

To contribute to Kaiord:

1. Fork and clone the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes following the code style guidelines
4. Add a changeset: pnpm exec changeset (for version-worthy changes)
5. Test locally: pnpm -r test and pnpm -r build
6. Submit a PR: All checks must pass before merging

For detailed contribution guidelines, development workflow, and code standards, see Contributing.

• Garmin FIT SDK (JavaScript) - Official FIT protocol implementation
• FIT Workout Files Cookbook - Guide to encoding workout files
• FIT File Types: Workout - Workout file type specification
• Training Center XML (TCX) - Garmin's XML-based format
• TCX Schema (XSD) - Official Garmin TCX schema definition
• Zwift Workout Format (ZWO) - Zwift's XML-based workout format

• Kiro - AI-powered development environment

MIT © 2025 Pablo Albaladejo
See LICENSE for details.

This project is built using Kiro for:

• Vibe coding → collaborative code generation with AI.
• Steering docs → maintain clean-code and testing principles.
• Specs → spec-driven implementation flow.
• Hooks → local automated validations (.kiro/hooks/*).
• GitHub MCP → direct GitHub integration for PR/issue management.

All configuration lives under .kiro/ and is version-controlled for reproducibility.

Kaiord uses the GitHub MCP server to enable direct GitHub interactions from Kiro:

# Run the automated setup script
./scripts/setup-github-mcp.sh

This configures:

• GitHub Personal Access Token authentication
• Docker-based MCP server
• Automatic PR/issue management capabilities

See GitHub MCP Integration for complete documentation.