Contribution Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
The bl1nk skill platform provides a structured environment for developing AI skills and infrastructure. These guidelines establish the standards for contributing new features, technical documentation, and CI/CD automation to ensure the platform remains stable, portable, and well-documented. Contributors are expected to follow a spec-driven development methodology, prioritizing real-world use cases over theoretical applications.
Sources: skill/CONTRIBUTING.md:3-9, specs/main/plan.md:12-16, Comprehensive.md:7-12
Core Development Philosophy
The project adheres to a "Constitution-Based Spec-Driven Development" (SDW) approach. This methodology ensures that every feature is governed by foundational principles and moves through defined phases before implementation begins.
The 7-Phase Workflow
- Constitution: Establish governing principles and technical standards.
- Specify: Define functional requirements without technical implementation details.
- Clarify: Resolve ambiguities through targeted questions.
- Plan: Create a technical strategy including architecture and data models.
- Tasks: Generate an actionable, dependency-ordered breakdown.
- Analyze: Validate consistency between tasks and requirements.
- Implement: Execute coding tasks following test-driven development.
Sources: plugins/spec-kit-skill/skills/spec-kit-skill/SKILL.md:9-17, plugins/kiro-skill/commands/kiro/spec.md:144-149
Developer Personas and Standards
Contributors should adopt a helpful, peer-to-peer communication style. Code should be minimal, avoiding overengineering or verbose implementations.
| Aspect | Standard |
|---|---|
| Tone | Relatable, digestible, and knowledgeable without being instructive. |
| Code Style | Absolute minimal code needed; focus on essential functionality only. |
| Design | Always generate responsive designs and use standard UI libraries like shadcn/ui. |
| Error Handling | Don't catch errors unless requested; allow them to bubble up for better debugging. |
Sources: plugins/kiro-skill/commands/kiro/spec.md:20-40, apps/client/src/prompts/system_prompt.ts:251-270
Skill Contribution Standards
New skills added to the platform must solve real problems and follow a specific directory and file structure.
Skill Requirements Checklist
- Real Use Case: Must be based on actual usage, not hypothetical scenarios.
- Documentation: Include clear instructions and real-world examples in
SKILL.md. - Safety: Ensure destructive operations require user confirmation.
- Portability: Must work across Claude.ai, Claude Code, and the API.
- Attribution: Credit original sources or inspiration workflows.
Sources: skill/CONTRIBUTING.md:13-25, skill/CONTRIBUTING.md:113-125
Skill Repository Structure
Each skill resides in its own kebab-case folder within the skills directory.
skill-name/
└── SKILL.md
The SKILL.md file must contain frontmatter (name and description), a "When to Use" section, and practical examples.
Sources: skill/CONTRIBUTING.md:27-35, plugins/kiro-skill/commands/kiro/spec.md:155-158
Technical Standards and Stack
The platform is a monorepo utilizing a modern TypeScript-based stack. All contributions must align with these technologies.
Primary Tech Stack
- Frontend: Next.js 15, React 19, Electron.
- Backend: Node.js, tRPC, Express.
- Database: SQLite (Phase 1) with Prisma ORM.
- Styling: Tailwind CSS and shadcn/ui components.
- Package Management: pnpm monorepo.
Sources: Comprehensive.md:43-48, apps/client/src/prompts/system_prompt.ts:316-330
Code Quality and AI Rules
A mandatory AI_RULES.md file defines local project standards. Contributors must prioritize the following:
- Type Safety: End-to-end type safety using Zod validation and tRPC.
- Modularity: Respect monorepo boundaries (client, server, shared).
- Directory Naming: Folder names must be lowercase (e.g.,
src/pages,src/components). - No Placeholders: Each implemented feature must be fully functional with no TODO comments.
Sources: apps/client/src/prompts/system_prompt.ts:241-250, apps/client/src/prompts/system_prompt.ts:311-315, specs/main/plan.md:65-75
Documentation and CI/CD Guidelines
The platform enforces a high standard for infrastructure documentation and automated testing.
Documentation Parity
All core documentation must maintain bilingual parity (English and Thai). Documents are categorized using a numbered prefix system.
The documentation structure ensures that every English guide has a corresponding Thai translation with cultural adaptation.
Sources: specs/main/plan.md:24-30, Comprehensive.md:152-160, specs/main/plan.md:105-115
Automation Workflows
Six primary GitHub Actions workflows govern the CI/CD pipeline.
| Workflow | Purpose | Trigger |
|---|---|---|
| CI Pipeline | Linting, Type-checking, Vitest/Playwright tests. | Push, PR |
| Electron Release | Multi-platform builds (Win/Mac/Linux) + Code signing. | Git tags (v*) |
| Database Checks | Prisma schema validation. | Schema changes |
| Security Scan | Dependency and secret analysis. | Weekly |
Sources: Comprehensive.md:23-35, specs/main/plan.md:40-50
Pull Request (PR) Process
- Fork and Branch: Create a feature branch (e.g.,
add-skill-name). - Implement: Add the skill or feature following the spec-driven workflow.
- Document: Update
README.mdand categories if adding a skill. - Validate: Ensure CI passes and code follows the
AI_RULES.md. - PR Description: Must explain the real-world problem solved and include an execution example.
Sources: skill/CONTRIBUTING.md:73-88, plugins/spec-kit-skill/skills/spec-kit-skill/SKILL.md:325-335
Contributors are encouraged to participate in the iterative review process, where each specification document (Requirements, Design, Tasks) is reviewed before final implementation begins.
Sources: plugins/kiro-skill/commands/kiro/spec.md:150-155, plugins/kiro-skill/skills/kiro-skill/SKILL.md:195-205
By adhering to these structured phases and quality standards, contributors help maintain the bl1nk skill platform as a high-quality, enterprise-grade IDE environment for AI development.