Contributing to Bootspring
How to contribute agents, patterns, skills, and improvements to Bootspring
Thank you for your interest in contributing to Bootspring. This guide covers everything you need to know to contribute effectively.
Ways to Contribute#
| Contribution Type | Description | Difficulty |
|---|---|---|
| Bug reports | Report issues you encounter | Easy |
| Documentation | Improve docs, fix typos | Easy |
| Custom patterns | Add new code patterns | Medium |
| Custom skills | Create reusable skill templates | Medium |
| Custom agents | Build specialized agents | Medium |
| Core features | Contribute to the Bootspring core | Advanced |
Getting Started#
1. Fork the Repository#
1# Fork on GitHub, then clone
2git clone https://github.com/YOUR_USERNAME/bootspring.git
3cd bootspring
4
5# Add upstream remote
6git remote add upstream https://github.com/girardmedia/bootspring.git2. Install Dependencies#
npm install3. Set Up Development Environment#
1# Build the project
2npm run build
3
4# Run tests
5npm test
6
7# Run linter
8npm run lint4. Create a Branch#
git checkout -b feature/my-contributionCreating Custom Agents#
Agents are specialized AI personas that provide domain expertise.
Agent Structure#
agents/
my-agent/
context.md # Required: Agent knowledge and expertise
patterns.md # Optional: Common patterns this agent uses
checklist.md # Optional: Review checklist for this domain
Step 1: Create the Directory#
mkdir -p agents/my-domain-expertStep 2: Create context.md#
This is the core of your agent. It defines the agent's expertise and behavior.
1# My Domain Expert
2
3## Role
4
5Brief description of what this agent does and when to use it.
6
7## Expertise
8
9- Area of expertise 1
10- Area of expertise 2
11- Area of expertise 3
12
13## Knowledge
14
15### Topic 1
16
17Detailed knowledge about topic 1...
18
19### Topic 2
20
21Detailed knowledge about topic 2...
22
23## Best Practices
24
251. Best practice 1
262. Best practice 2
273. Best practice 3
28
29## Common Patterns
30
31### Pattern Name
32
33Description and example code...
34
35## Anti-patterns
36
37Things to avoid in this domain...
38
39## Checklist
40
41- [ ] Checklist item 1
42- [ ] Checklist item 2Step 3: Register the Agent#
Add to bootspring.config.js:
module.exports = {
agents: {
custom: ['my-domain-expert']
}
};Agent Guidelines#
- Be specific - Focus on a well-defined domain
- Be practical - Include actionable patterns and examples
- Be comprehensive - Cover common scenarios thoroughly
- Be opinionated - Recommend best practices, not just options
- Include context - Explain the "why" behind recommendations
Example: Creating a GraphQL Expert Agent#
1# GraphQL Expert
2
3## Role
4
5Specialized in GraphQL API design, implementation, and optimization for Node.js and Next.js applications.
6
7## Expertise
8
9- GraphQL schema design
10- Resolvers and data loaders
11- Query optimization
12- Real-time subscriptions
13- Apollo Server and Client
14- Code generation with GraphQL Codegen
15
16## Knowledge
17
18### Schema Design
19
20Always start with schema-first design. Define your types before implementation:
21
22\`\`\`graphql
23type User {
24 id: ID!
25 email: String!
26 name: String
27 posts: [Post!]!
28}
29
30type Post {
31 id: ID!
32 title: String!
33 content: String!
34 author: User!
35}
36\`\`\`
37
38### Resolvers
39
40Keep resolvers thin. Business logic belongs in services:
41
42\`\`\`typescript
43const resolvers = {
44 Query: {
45 user: (_, { id }, { services }) => services.user.findById(id),
46 },
47 User: {
48 posts: (user, _, { loaders }) => loaders.postsByUserId.load(user.id),
49 },
50};
51\`\`\`
52
53## Best Practices
54
551. Use DataLoader to prevent N+1 queries
562. Implement proper error handling with custom error types
573. Add depth limiting to prevent malicious queries
584. Use persisted queries in productionCreating Custom Patterns#
Patterns are production-ready code templates for common tasks.
Pattern Structure#
skills/
category/
pattern-name.md
Pattern Template#
1# Pattern Name
2
3Brief description of what this pattern does.
4
5## Use When
6
7- Scenario 1
8- Scenario 2
9
10## Implementation
11
12\`\`\`typescript
13// Production-ready code example
14\`\`\`
15
16## Configuration
17
18Options and customization...
19
20## Testing
21
22How to test this pattern...
23
24## Related Patterns
25
26- Related pattern 1
27- Related pattern 2Pattern Guidelines#
- Production-ready - Code should work out of the box
- Well-documented - Explain what the code does
- Tested - Include test examples
- Configurable - Allow customization where appropriate
- TypeScript-first - Use TypeScript with proper types
Creating Custom Skills#
Skills are reusable templates that generate code based on parameters.
Skill Structure#
1// skills/my-skill/index.ts
2export const skill = {
3 name: 'my-skill',
4 description: 'What this skill does',
5
6 parameters: {
7 name: { type: 'string', required: true },
8 options: { type: 'object', required: false },
9 },
10
11 template: (params) => `
12 // Generated code based on ${params.name}
13 `,
14
15 examples: [
16 {
17 input: { name: 'example' },
18 description: 'Basic usage',
19 },
20 ],
21};Skill Guidelines#
- Clear parameters - Document all inputs
- Sensible defaults - Provide good default values
- Multiple examples - Show various use cases
- Error handling - Validate inputs
Code Style Guidelines#
TypeScript#
1// Use explicit types
2function processUser(user: User): ProcessedUser {
3 // ...
4}
5
6// Use interfaces for objects
7interface UserConfig {
8 name: string;
9 email: string;
10 settings?: UserSettings;
11}
12
13// Use enums for fixed values
14enum UserRole {
15 Admin = 'admin',
16 User = 'user',
17 Guest = 'guest',
18}Naming Conventions#
| Type | Convention | Example |
|---|---|---|
| Files | kebab-case | user-service.ts |
| Classes | PascalCase | UserService |
| Functions | camelCase | getUserById |
| Constants | SCREAMING_SNAKE_CASE | MAX_RETRIES |
| Types/Interfaces | PascalCase | UserConfig |
| Agents | kebab-case | database-expert |
| Patterns | kebab-case | api-endpoint |
Code Organization#
1// 1. Imports (external first, then internal)
2import { z } from 'zod';
3import { prisma } from '@/lib/prisma';
4
5// 2. Types
6interface UserInput {
7 name: string;
8 email: string;
9}
10
11// 3. Constants
12const MAX_USERS = 100;
13
14// 4. Main implementation
15export function createUser(input: UserInput) {
16 // ...
17}
18
19// 5. Helper functions (private)
20function validateEmail(email: string): boolean {
21 // ...
22}Documentation#
1/**
2 * Creates a new user in the database
3 *
4 * @param input - User creation parameters
5 * @param input.name - User's display name
6 * @param input.email - User's email address
7 * @returns The created user object
8 * @throws {ValidationError} If email is invalid
9 *
10 * @example
11 * const user = await createUser({ name: 'John', email: 'john@example.com' });
12 */
13export async function createUser(input: UserInput): Promise<User> {
14 // ...
15}Submitting Pull Requests#
Before Submitting#
- Run tests:
npm test - Run linter:
npm run lint - Build:
npm run build - Update docs if needed
PR Guidelines#
- Clear title - Describe what the PR does
- Description - Explain the changes and why
- Link issues - Reference related issues
- Small PRs - Keep changes focused
- Tests - Add tests for new functionality
Commit Messages#
Use conventional commits:
feat: add graphql-expert agent
fix: resolve database connection issue
docs: update contributing guide
refactor: simplify agent loading logic
test: add tests for quality gates
chore: update dependencies
PR Template#
1## Summary
2
3Brief description of changes.
4
5## Changes
6
7- Change 1
8- Change 2
9- Change 3
10
11## Testing
12
13How to test these changes.
14
15## Related Issues
16
17Closes #123Development Workflow#
1. Sync with Upstream#
git fetch upstream
git rebase upstream/main2. Make Changes#
# Work on your feature
git add .
git commit -m "feat: add my feature"3. Run Quality Checks#
npm run lint
npm test
npm run build4. Push and Create PR#
git push origin feature/my-contribution
# Create PR on GitHub5. Address Review Feedback#
# Make requested changes
git add .
git commit -m "fix: address review feedback"
git push origin feature/my-contributionTesting#
Running Tests#
1# Run all tests
2npm test
3
4# Run specific tests
5npm test -- --grep "agent"
6
7# Run with coverage
8npm run test:coverageWriting Tests#
1import { describe, it, expect } from 'vitest';
2import { loadAgent } from '../agents';
3
4describe('loadAgent', () => {
5 it('should load a valid agent', async () => {
6 const agent = await loadAgent('frontend-expert');
7 expect(agent).toBeDefined();
8 expect(agent.name).toBe('frontend-expert');
9 });
10
11 it('should throw for invalid agent', async () => {
12 await expect(loadAgent('nonexistent')).rejects.toThrow();
13 });
14});Getting Help#
Resources#
- GitHub Issues - Report bugs and request features
- Discussions - Ask questions and share ideas
- Documentation - Read the docs
Questions?#
If you're unsure about anything:
- Check existing issues and discussions
- Ask in GitHub Discussions
- Open a draft PR for feedback
Recognition#
Contributors are recognized in:
CONTRIBUTORS.mdfile- Release notes
- Documentation credits
Thank you for contributing to Bootspring!
Related#
- All Agents - See existing agents for examples
- Skills Overview - Understand skill structure
- Code Patterns - Browse existing patterns
- CLI Reference - Command documentation