SWIC - Story Workflow Integration Controller

SWIC (Story Workflow Integration Controller) is an MCP (Model Context Protocol) server for managing stories, subtasks, and pipelines through structured workflows. It provides both a CLI and MCP tools for Claude to orchestrate development workflows.

Features

• Story Management: Organize work into structured stories with specs, designs, and subtasks
• MCP Integration: Native integration with Claude Code via Model Context Protocol
• CLI Tools: Command-line interface for direct manipulation
• Document Management: Project and shared document storage with namespacing
• Workflow Orchestration: Automated workflows for story creation, design, and implementation

Installation

Using npm

npm install -g @kelceyp/swic

Using bun

bun add -g @kelceyp/swic

As a project dependency

# npm
npm install --save-dev @kelceyp/swic

# bun
bun add -D @kelceyp/swic

Quick Start

CLI Usage

# Create a doc in project scope
swic doc create project quickstart "# Quick Start\n\nGetting started with SWIC"

# List all docs
swic doc list

# Read a doc
swic doc read project quickstart

# Edit a doc
swic doc edit project quickstart --replace-once "Quick Start" "Getting Started"

# Delete a doc
swic doc delete project quickstart

MCP Integration with Claude

Add to your .mcp.json or Claude Desktop config:

{
  "mcpServers": {
    "swic": {
      "command": "swic-mcp"
    }
  }
}

Once configured, Claude can access SWIC tools:

User: Create a project doc called "architecture" with our system design

Claude: *uses swic doc_create tool*

Directory Structure

SWIC creates two data directories on first use:

• .swic/ - Project-specific data (created in your project root)

  • docs/ - Project documents
  • stories/ - Story workflows

• ~/.swic/ - Shared data (created in your home directory)

  • docs/ - Shared documents across all projects
  • templates/ - Reusable templates
  • workflows/ - Workflow definitions

These directories are created automatically when you first use SWIC.

Available MCP Tools

When used as an MCP server, SWIC provides these tools to Claude:

• doc_create - Create a new document
• doc_read - Read one or more documents
• doc_edit - Edit document content
• doc_delete - Delete one or more documents
• doc_list - List all documents
• doc_move - Move or rename documents

CLI Commands

Document Management

# Create
swic doc create <scope> <path> [content]

# Read
swic doc read <identifier>

# Edit
swic doc edit <identifier> --replace-once "old" "new"
swic doc edit <identifier> --replace-all "old" "new"
swic doc edit <identifier> --replace-all-content "new content"

# Delete
swic doc delete <identifier>

# List
swic doc list [scope]

# Move
swic doc move <source> <destination>

Scopes: project or shared

Development

Building from Source

# Clone the repository
git clone https://github.com/kelceyp/swic.git
cd swic

# Install dependencies
bun install

# Build distribution
bun run build

# Test locally
./dist/cli/cli.js doc list

Running Tests

# Run E2E tests locally
bun run test:e2e:local

# Run E2E tests in Docker
bun run test:e2e

Project Philosophy

SWIC follows these core principles:

1. Don't be helpful - Do only what's asked, no gold-plating
2. Be brutal with scope - No extra features, no "while I'm at it"
3. Follow the story process - Specs define WHAT, designs define HOW
4. RTFM - Research before implementing
5. No backwards compatibility - Breaking changes are fine
6. No fallbacks or defaults - Fail fast, don't mask issues
7. Measure twice, cut once - Shift left, ask questions, do designs
8. Don't run ahead of the user - Work with the user
9. No time estimates - They're always wrong, just do the work

See CLAUDE.md for full development guidelines.

License

MIT

Author

Paul Kelcey

Repository

https://github.com/kelceyp/swic

Issues

Report issues at: https://github.com/kelceyp/swic/issues