How to Contribute to Fabriq: Starting with a Blog Post

TL;DR. We designed Fabriq's contribution paths to match different skills and interests. If you're a writer, start with a blog post. If you're a designer, tackle a UI issue. If you're a plugin developer, the plugin SDK is ready. If you're a Rustacean, the Tree-sitter integration needs love. This post maps every path with concrete starting points, expected time investment, and the review process.

---

The two misconceptions about open source contribution#

Misconception 1: "I need to write code to contribute."

False. Documentation, design, testing, community support, and issue triage are all valuable contributions. In an AI tooling project like Fabriq, writing and design are especially impactful because the product is about legibility — making things visible and understandable.

Misconception 2: "I need to understand the whole codebase first."

Also false. Every contribution path has a natural entry point that requires minimal context. A blog post about Fabriq's philosophy requires reading the README (5 minutes) and possibly one ADR. A UI fix requires understanding one component. A plugin requires the plugin SDK README.

Contribution path map#

Path	Skill	Time to first contribution	Entry point
Writing	Technical writing, storytelling	2–4 hours	apps/website/content/blog/
Documentation	Technical writing, clarity	1–3 hours	docs/ directory
UI/Design	React, CSS, design sense	2–8 hours	"good first issue" label
Plugin development	TypeScript, API design	4–12 hours	packages/plugin-sdk/
Core engineering	TypeScript, Node.js, Electron	4–40 hours	packages/services/
CDR/AST	TypeScript, Tree-sitter, compilers	8–40 hours	packages/engine-client/
Testing	Attention to detail, patience	1–4 hours	Uncovered paths in packages/*/__tests__/
Bug reports	Debugging, clear writing	30 min–2 hours	GitHub Issues
Community	Empathy, communication	ongoing	GitHub Discussions, issues

Let's walk through each path in detail.

Path 1: Writing (blog posts)#

The fastest way to contribute meaningfully. Fabriq's blog is a key part of the product — it's how we explain the philosophy, architecture, and roadmap.

What you need#

• A topic you find interesting about Fabriq or AI-assisted development
• 2–4 hours of focused writing time
• Basic Markdown/MDX familiarity

How to start#

1. Read 2–3 existing blog posts to understand the tone and structure
2. Choose a topic — something you've thought about: "How I use Fabriq for X," "Why Y matters in AI development tools," "Lessons from migrating Z to Fabriq"
3. Create a draft — Write in MDX format with frontmatter (title, date, author, excerpt, tags, category)
4. Submit a PR — Use the blog post template from apps/website/content/blog/

Example topics#

• "Setting up Fabriq with a team of 5: what worked and what didn't"
• "Why we switched from [other tool] to Fabriq for AI-assisted development"
• "Advanced dimension rules: customizing Fabriq for your team's workflow"
• "How Fabriq's audit trail helped us debug a production issue"

Path 2: Documentation#

Good documentation is harder to write than good code — and more valuable.

What you need#

• Clear writing
• Empathy for readers who are new to the project

How to start#

Browse the docs/ directory. Find something that's:

• Missing — a topic that should be documented but isn't
• Stale — a doc that refers to an older API or workflow
• Confusing — you had to figure something out through trial and error that the docs should have explained

Common gaps: onboarding guide for new users, FAQ, troubleshooting common issues, integration guides for specific tools.

Path 3: UI/Design#

Fabriq's UI is built with React + TypeScript + Tailwind CSS v4. The design system tokens live in packages/ui/src/tokens/.

What you need#

• React and TypeScript experience
• Familiarity with Tailwind CSS

How to start#

Look for issues labeled good first issue or ui in the GitHub issue tracker. Common UI tasks:

• Polishing a component that feels rough
• Adding dark mode variants
• Improving responsive layout
• Fixing accessibility issues

The design system is documented in docs/design-tokens.md and docs/ui-design.md.

Path 4: Plugin development#

Plugins extend Fabriq with custom capabilities — new sidebar panels, custom feature stages, agent backend integrations.

What you need#

• TypeScript
• Understanding of the plugin manifest system

How to start#

1. Read packages/plugin-sdk/README.md
2. Look at example plugins in packages/plugins/
3. Implement a plugin that solves a real need

Plugin ideas:

• A Jira integration that links features to tickets
• A diagram generator for CDR artifacts
• A workspace health dashboard
• A custom stage step for your team's workflow

Path 5: Core engineering#

Fabriq's core services (packages/services/) handle feature lifecycle, validation, gate checking, and close pipelines.

What you need#

• TypeScript proficiency
• Understanding of the engine-client pattern (typed IPC capability calls)

How to start#

Check the roadmap for unstarted or partial items. As of this writing:

• Validation pipeline (track B) — validation.case.generate and validation.run need implementation
• Close hook pipeline (track A2) — five-step close state machine needs completion

These are well-scoped with existing type definitions, test files, and spec documents.

Path 6: CDR / AST#

The Cognitive Development Record pipeline is the most technically interesting part of Fabriq — it's where we combine LLM scanning with deterministic Tree-sitter validation.

What you need#

• TypeScript
• Interest in static analysis/compiler concepts
• Familiarity with Tree-sitter is a plus but not required

How to start#

Explore packages/engine-client/src/ — especially the CodeGraph integration and evidence validation. Look for:

• Additional language support (adding Tree-sitter grammars)
• Improved symbol resolution (cross-file reference tracking)
• Enhanced evidence validation rules

Path 7: Testing#

Tests are the safety net for a fast-moving AI tooling project.

What you need#

• Attention to detail
• Methodical thinking

How to start#

Run the existing test suite. Find uncovered paths. Add tests for:

• Edge cases in feature lifecycle
• IPC channel validation errors
• Dimension rule enforcement
• Audit log format compliance

Our test framework is Vitest (node --test compatible). Test files live alongside source code in __tests__/ directories.

Path 8: Bug reports#

A well-written bug report is as valuable as a PR.

What makes a great bug report#

• One bug per report. Don't list three unrelated issues in one issue.
• Reproduction steps. From "open Fabriq" to "see the bug," every step.
• Expected vs. actual behavior. What should happen vs. what does happen.
• Environment. OS, Fabriq version, agent backend version.
• Logs. Relevant entries from .dapei/audit/ or the DevTools console.
• Screenshots. If the bug is visual.

Path 9: Community#

Answering questions in GitHub Discussions, reviewing PRs, helping new contributors navigate the codebase — these are invisible but essential contributions.

What you need#

• Familiarity with the project
• Patience and empathy

How to start#

Watch the GitHub Discussions and Issues. Answer questions that you know the answer to. Point people to the right docs. Suggest improvements to the contributor experience.

The contribution flow#

Regardless of the path, the flow is the same:

1. Find your entry point. Use this guide, the issue tracker, or the roadmap.
2. Engage early. Open a Discussion or issue to describe what you want to do. Get feedback before investing significant time.
3. Contribute. Follow the existing patterns. Include tests where applicable. Update docs if your change affects user-facing behavior.
4. Review. A maintainer or core contributor reviews your contribution. Expect 1–3 review cycles for code changes; less for docs and writing.
5. Ship. Once approved, the contribution is merged. Blog posts are published on the Fabriq website.

We're here to help#

The best open source communities are the ones that make contributors feel welcome regardless of experience level. Fabriq aspires to be that kind of community.

If you're not sure where to start: open a Discussion, say "I want to contribute but I'm not sure how," and describe your skills and interests. We'll find a path.

---

Ready to contribute? Fork the repo, read the developer guide, and join the Discussions.