Skip to content
/

colign

colign · colign/colign · ★ 4 · last commit 2026-05-02

Provides a team-alignment platform for spec-driven development where teams discuss, write, and co-review structured proposals with BDD acceptance criteria before any AI agent writes code.

Best whenThe bottleneck in AI-assisted development is upstream team alignment, not code generation speed — building shared spec infrastructure for teams matters more …
Skip ifAI vibe coding without team alignment, Monolithic 30-page PRDs (replaced by two-layer architecture)
vs seeds
openspec(also multi-tool), colign is a full-stack web application rather than a CLI tool. The only framework in this corpus desi…
Primitive shape 16 total
Skills 6 MCP tools 10
00

Summary

colign — Summary

colign is an open-source, self-hosted spec-driven development platform for teams: a Go+Next.js web application with real-time collaborative spec editing, a structured Draft→Design→Review→Ready workflow, project memory (persistent strategic context), and an MCP server for connecting Claude Code, Cursor, or any MCP-compatible AI tool to read and write specs. Unlike the file-based spec frameworks in this corpus, colign is a full-stack application (Postgres + Redis backend, Docker Compose deployment) providing team alignment infrastructure — the spec repository is the platform itself, not markdown files. It ships a Claude Code plugin with 6 workflow skills and an MCP server with 10 tools. The framework's core insight: "AI that writes code already exists. Colign makes sure your team is looking at the same thing before the code gets written." With 4 stars, it is the least-starred framework in this batch, and still in early development (2 contributors). Compared to seeds, colign is closest to kiro (both provide a structured spec+workflow platform for teams) but is open-source, self-hosted, and multi-tool where Kiro is a proprietary IDE.

01

Overview

colign — Origin & Philosophy

Origin

Created by gobenpark (Go/TypeScript developer). Last commit May 2026. 4 stars, 2 contributors, AGPL-3.0 license. Early-stage product with active development.

Core Philosophy (verbatim from README)

"AI vibe coding has made individual developers incredibly productive. Claude Code, Cursor, Copilot — there are already powerful tools for writing code on your own. But real software is never built alone."

"AI that writes code already exists. Colign makes sure your team is looking at the same thing before the code gets written."

"Working in a team means aligning on 'what to build' before writing any code. You gather requirements, discuss specs, define acceptance criteria, get reviews, and only then start implementing. Most AI development tools don't address this upstream collaboration — the discussion, alignment, and spec writing that happens before code."

Two-Layer Spec Architecture

colign explicitly criticizes traditional PRDs ("30-page document, one layer"):

  1. Project Memory — strategic context (domain rules, constraints, target users, technical decisions). Written once, referenced by every Change. Rarely changes.
  2. Structured Proposal — tactical spec per change, lightweight, structured for both humans and AI agents:
    • Problem (required) — why is this needed?
    • Scope (required) — what specifically changes?
    • Out of Scope (optional) — what's explicitly excluded?
    • Approach (optional) — technical direction
    • Acceptance Criteria (required) — Given/When/Then

Target Users

Teams using AI coding tools, not solo developers. The value proposition is upstream alignment (spec writing + review) before any AI agent touches code.

02

Architecture

colign — Architecture

Distribution

Self-hosted application (Docker Compose). Also has a SaaS offering at colign.co.

Install (Self-hosted)

docker-compose up --build        # Start API + DB + Redis
cd web && npm install && npm run dev  # Frontend (separate)

Tech Stack

  • API: Go 1.26+ (cmd/api/)
  • Frontend: Next.js 16, React, TypeScript (web/)
  • Real-time collaboration: Hocuspocus (collaborative editing protocol)
  • Database: PostgreSQL (migrations in migrations/)
  • Cache/Queue: Redis
  • Proto: gRPC/Protobuf (proto/, buf-generated)
  • MCP: Go MCP server (cmd/mcp/)
  • Containerization: Docker, Helm (Kubernetes support)

Directory Structure

cmd/
├── api/        # Go API server
└── mcp/        # MCP server binary
web/            # Next.js frontend
internal/       # Go business logic
migrations/     # PostgreSQL migrations
proto/          # Protobuf definitions
hocuspocus/     # Real-time collaboration
design-system/  # Component library
ee/             # Enterprise Edition features
helm/           # Kubernetes Helm chart

Claude Code Plugin

/plugin marketplace add https://github.com/colign/plugin
/plugin install colign@colign
/reload-plugins

(Installs from colign/plugin — separate repository, not in this repo)

MCP Server (SaaS)

{
  "mcpServers": {
    "colign": {
      "url": "https://api.colign.co/mcp",
      "headers": { "Authorization": "Bearer col_your_token_here" }
    }
  }
}

MCP Server (Self-hosted/Local)

go build -o colign-mcp ./cmd/mcp
COLIGN_API_TOKEN=col_... COLIGN_API_URL=http://localhost:8080 ./colign-mcp

Target AI Tools

Claude Code, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible AI tool.

03

Components

colign — Components

Claude Code Plugin Skills (6 skills)

Following the change lifecycle: onboard → explore → propose → plan → implement → complete

Skill Stage Description
colign:onboard Setup Verify MCP connection and API token
colign:explore Any Browse projects, read specs, check status
colign:propose Draft → Problem Write a structured proposal
colign:plan Problem → Solution Break proposal into architecture and tasks
colign:implement Solution → Review Code against the spec, update task progress
colign:complete Review → Done Verify all tasks done, advance workflow

Skills trigger automatically by context (e.g., "implement the next task") or explicitly via /colign:implement.

MCP Server Tools (10 tools)

Tool Description
list_projects List all accessible projects
get_change Get change details including stage
read_spec Read a spec document (proposal, design, spec, tasks)
write_spec Write or update a spec document
list_tasks List implementation tasks for a change
update_task Update a task's status (todo, in_progress, done)
suggest_spec Get suggestions for improving a spec
list_acceptance_criteria List acceptance criteria (Given/When/Then)
create_acceptance_criteria Create BDD-style acceptance criteria
delete_acceptance_criteria Delete an acceptance criteria by ID

Workflow States (per Change)

Draft → Design → Review → Ready

Web Application Features

  • AI Spec Generation (using your API key)
  • Real-time co-editing (Hocuspocus)
  • Dashboard (spec status overview)
  • Inbox (notifications, review requests)
  • Structured Proposal editor
  • Project Memory editor
  • Acceptance Criteria management (Given/When/Then)

No Hooks

Zero Claude Code lifecycle hooks.

05

Prompts

colign — Prompt Files

Note: The Claude Code plugin lives in colign/plugin (separate repository). Prompt files were not fetchable from the main colign/colign repo. The CLAUDE.md and structural files below are the primary sources.

Excerpt 1: CLAUDE.md — Development Standards for Colign Contributors

# Colign

## Testing
- Always use `/tdd` skill when changing code — write tests first (RED → GREEN → REFACTOR)
- Unit tests required for all Go packages, target 80%+ coverage
- Auth/security code (auth, apitoken, oauth, middleware) targets 100% coverage

## Code Quality
- Always handle error returns. Never use `_, _ =` to discard errors — check or log them
- Logging: use `log/slog` (structured logging). Do not use `fmt.Println`, `log.Printf`, or third-party loggers
- Must pass golangci-lint (errcheck)
- commitlint: conventional commits format, subject must start lowercase

## Database
- Always invoke `/database-design:postgresql` skill before writing or modifying migration SQL
- Prefer `TEXT` over `VARCHAR(n)` — use `CHECK (LENGTH(col) <= n)` if limit needed
- Use `BIGINT GENERATED ALWAYS AS IDENTITY` — never `BIGSERIAL` or `SERIAL`
- Always add indexes on FK columns manually — PostgreSQL does not auto-index FKs
- Use `TIMESTAMPTZ`, never `TIMESTAMP` without timezone

Technique: Database convention-as-law — specific SQL anti-patterns are banned by name (BIGSERIAL, SERIAL, TIMESTAMP without TZ). This prevents a well-known class of PostgreSQL migration debt accumulated over time.

Excerpt 2: Structured Proposal Format (from README)

| Section | Required | Purpose |
|---------|:--------:|---------|
| **Problem** | Yes | Why is this change needed? |
| **Scope** | Yes | What specifically will change? |
| **Out of Scope** | No | What is explicitly NOT part of this? |
| **Approach** | No | Technical direction and rationale |
| **Acceptance Criteria** | Yes | Given/When/Then scenarios |

Technique: Required/optional schema enforcement — Problem, Scope, and Acceptance Criteria are required fields; Approach and Out of Scope are optional. This enforces minimum spec quality without over-prescribing format.

Excerpt 3: Plugin Skill Chain (from README)

onboard → explore → propose → plan → implement → complete

Technique: Contextual skill triggering — Skills trigger automatically by context ("implement the next task") or explicitly via /colign:implement. The skill chain mirrors the human review workflow stages, making it natural for agents to pick up where humans left off.

Prompting Techniques Summary

  1. Required schema enforcement — Problem/Scope/Acceptance Criteria required, others optional
  2. Two-layer spec architecture — Project Memory (strategic, stable) + Structured Proposal (tactical, per-change)
  3. Convention-as-law — SQL antipatterns banned by CLAUDE.md
  4. BDD Acceptance Criteria — Given/When/Then enforced as the test specification format
  5. TDD enforcement/tdd skill required before any code change (for Colign's own codebase)
09

Uniqueness

colign — Uniqueness & Positioning

differs_from_seeds

Closest seed is kiro (both provide a structured spec+workflow platform for teams), but colign is open-source, self-hosted, and multi-tool where Kiro is a proprietary IDE. The two-layer spec architecture (Project Memory + Structured Proposal) is similar to Kiro's steering/ folder + per-feature spec pattern. Against openspec (also multi-tool spec pipeline), colign is a full-stack web platform with real-time collaboration, PostgreSQL backend, and team review workflows — not a CLI tool. Against all other seeds that are single-developer focused, colign is the only framework explicitly designed for team alignment before AI coding begins.

Unique Positioning

colign is the only framework in this corpus that:

  1. Is a full-stack web application (Go API + Next.js + Postgres + Redis), not a CLI or plugin
  2. Provides real-time collaborative spec editing (Hocuspocus)
  3. Has a human team review gate as a first-class workflow stage
  4. Stores specs in a database (not the project filesystem)
  5. Ships both a SaaS offering and a self-hosted option
  6. Targets the "upstream alignment" problem (before code is written) rather than the "code guidance" problem

Observable Failure Modes

  1. Very early stage: 4 stars, 2 contributors — significant product and adoption risk.
  2. Self-hosting complexity: Docker Compose + Postgres + Redis + Hocuspocus + proto generation requires significant infrastructure knowledge.
  3. Plugin in separate repo: Claude Code plugin lives in colign/plugin (not this repo); easier to lose sync.
  4. AGPL-3.0 license: strong copyleft; enterprise adoption may be restricted.
  5. No TDD for users: despite requiring TDD for Colign's own development, there is no mechanism to enforce TDD for projects using Colign.
  6. No file-based fallback: if the Colign platform is down, agents lose spec access; no file-based degradation mode.

Explicit Antipatterns

  • "AI vibe coding" without team alignment on what to build
  • 30-page monolithic PRD documents (replaced by two-layer: Project Memory + Structured Proposal)
  • Separate spec tooling per developer instead of shared team spec platform
04

Workflow

colign — Workflow

Platform-Side Workflow (team alignment)

Phase Actor Action Artifact
1. Project Setup Admin Create project, write Project Memory Project Memory (domain rules, constraints, target users)
2. Propose Developer Create Change, write Structured Proposal Proposal (Problem, Scope, Approach, Acceptance Criteria)
3. Design Team Co-edit proposal in real-time Refined proposal
4. Review Reviewers Review spec, approve or request changes Review → Ready state transition
5. Ready Any Spec approved, implementation may begin Approved spec
6. Implement Developer/AI Code against approved spec, update task progress Code + task status updates
7. Done Developer/AI All tasks complete, advance to Done Completed change

Workflow States

Draft → Design → Review → Ready → In Progress → Done

Approval Gates

Gate Type Description
Draft → Design freetext-clarify Team reviews and edits the proposal
Review → Ready yes-no Explicit reviewer approval required
Ready → Implementation implicit Spec must be in Ready state before agent implements

Agent-Side Workflow (via Claude Code plugin)

/colign:onboard   → verify MCP connection
/colign:explore   → browse specs, check status
/colign:propose   → write structured proposal
/colign:plan      → break proposal into tasks
/colign:implement → code against spec, update tasks
/colign:complete  → verify done, advance workflow

Structured Proposal Schema

---
Problem: "Why is this change needed?"  (required)
Scope: "What specifically will change?" (required)
Out of Scope: "What is excluded?"       (optional)
Approach: "Technical direction"         (optional)
Acceptance Criteria: Given/When/Then    (required, BDD)
---
06

Memory Context

colign — Memory & Context

State Storage

PostgreSQL database (self-hosted or SaaS). All project memory, proposals, acceptance criteria, and task status stored server-side.

Two-Layer Memory Architecture

  1. Project Memory — persistent strategic context per project (domain rules, constraints, target users, technical decisions). Written once, shared across all changes.
  2. Change-level Spec — per-change structured proposal with Problem, Scope, Approach, Acceptance Criteria, and implementation tasks.

Cross-Session Handoff

Yes — all state is in the database. Any session can query current spec status via MCP tools (get_change, list_tasks, read_spec).

Context for AI Agents

AI agents get context through:

  • read_spec MCP tool — reads the current approved spec
  • list_tasks MCP tool — shows implementation task list with status
  • get_change MCP tool — gets change details including current workflow stage
  • update_task MCP tool — marks tasks as in_progress/done

Real-time Collaboration

Hocuspocus provides operational transform-based real-time co-editing of spec documents. Multiple team members can edit the same proposal simultaneously.

Memory Type

Remote database (PostgreSQL via SaaS API or self-hosted).

Persistence Scope

Global (server-side, all projects).

Compaction

None. Specs live as-is in the database.

07

Orchestration

colign — Orchestration

Multi-Agent

No. colign provides spec infrastructure for a single AI agent per session to read and implement against. Multiple human team members contribute to specs (real-time co-editing), but the implementation agent is single-agent.

Orchestration Pattern

Sequential. The workflow states (Draft → Design → Review → Ready → Done) enforce sequential progression with human gates between stages.

Execution Mode

Interactive-loop. Agents use MCP tools iteratively within a session to read specs, update task status, and advance workflow.

Isolation Mechanism

None. Code changes happen in the agent's working directory.

Multi-Model

No. colign supports any MCP-compatible AI tool but does not route different models to different roles.

Consensus Mechanism

None at the software level. Team review (human consensus) is built into the Draft → Review → Ready workflow, but this is a human-approval workflow, not a distributed consensus protocol.

Auto-Validators

  • Platform validates Structured Proposal has required fields (Problem, Scope, Acceptance Criteria) before transition to Review stage
  • suggest_spec MCP tool — AI-powered spec improvement suggestions

TDD Enforcement

Required for colign's own development (CLAUDE.md mandates /tdd skill), but not enforced for end-user projects.

Git Automation

None. Colign tracks task status in the platform but does not create commits or PRs automatically.

Cross-Tool Portability

High for MCP integration. Low for the web platform itself (requires self-hosting or SaaS account).

08

Ui Cli Surface

colign — UI & CLI Surface

CLI Binary

None. colign has no standalone CLI binary for end users.

Web Application (Primary UI)

  • URL: https://colign.co (SaaS) or http://localhost:3000 (self-hosted)
  • Tech Stack: Next.js 16, React, TypeScript, Tailwind CSS
  • Features:
    • Dashboard — spec status overview
    • Inbox — notifications and review requests
    • Structured Proposal editor with real-time co-editing
    • Project Memory editor
    • Acceptance Criteria management (Given/When/Then BDD)
    • AI spec generation (using user's API key)
    • Settings > AI & API Keys — token management

MCP Server

  • SaaS endpoint: https://api.colign.co/mcp (Streamable HTTP, no binary)
  • Self-hosted binary: colign-mcp (Go binary compiled from cmd/mcp/)
  • Protocol: Streamable HTTP (SaaS) or stdio (local)

Claude Code Plugin

  • Install: /plugin marketplace add https://github.com/colign/plugin
  • Skills: 6 skills (onboard, explore, propose, plan, implement, complete)
  • OAuth login: browser opens for authentication on /reload-plugins

Admin Dashboard

Colign has an Enterprise Edition (ee/ directory) suggesting additional admin/enterprise features.

Observability

  • Web dashboard shows spec status per change
  • get_change MCP tool for programmatic status
  • list_tasks MCP tool for task tracking

Related frameworks

same archetype · same primary tool · same memory type

Taskmaster AI ★ 27k

Converts a PRD into a dependency-ordered JSON task graph that AI coding agents execute one task at a time, eliminating context…

ccmemory ★ 1

Accumulates decisions, corrections, and failed approaches from Claude Code sessions into a queryable Neo4j graph so each new…

Pimzino spec-workflow-mcp ★ 4.2k

MCP server providing spec-driven development workflow with dashboard-backed approval gates, implementation logging, and VSCode…

MCP Shrimp Task Manager ★ 2.1k

Convert natural language requests into structured AI development tasks with chain-of-thought enforcement, reflection gates, and…

Bernstein ★ 460

Govern parallel CLI coding agents with a deterministic Python scheduler, HMAC-chained audit trail, and compliance-ready signed…

LeanSpec ★ 252

Provides a unified spec CLI and MCP server over any existing spec backend (markdown, GitHub Issues, ADO), making spec-driven…