Skip to content

joi-fairshare/agentic-workflow

BranchesTags

Repository files navigation

Agentic Workflow

A portable Claude Code workflow toolkit: custom skills, configuration archive, repo bootstrapper, a bidirectional MCP bridge for multi-agent communication, and token-efficiency tools (rtk command rewriter, headroom context compressor).

Workflow: Product Vision → Ship

This toolkit supports an end-to-end product workflow where AI sessions replace documents — the goal is GitHub issues as the single source of truth, not a proliferating collection of local markdown files.

Stage 1 — Ideation

/withInterview

Human in the loop: You're in the hot seat. The agent interviews you — asking questions, challenging assumptions, surfacing contradictions — while you answer in your own words. The output is a coherent problem statement and set of goals distilled from your raw thinking, not polished prose you had to write yourself.

Stage 2 — Spec & Design Doc

/officeHours [feature or problem]

Human in the loop: This is a back-and-forth collaboration. The agent proposes requirements, you push back. It drafts the technical design, you redirect priorities and flag constraints it doesn't know about. Think of it as a YC office hours session — you leave with decisions made, not just options listed. It also brings structure to multi-team collaboration: product and engineering can align on vision, scope, and trade-offs in a shared session before anyone writes a line of code. The output lands in ~/.agentic-workflow/<repo>/plans/:

File Owner Contents
product.md Product Problem statement, EARS requirements, acceptance criteria, success metrics, MVP scope
engineering.md Engineering Current state, approach, architecture decisions, open questions
design-brief.md Design Experience goals, key interactions, UX requirements, design language reference
TASKS.md Engineering Atomic task breakdown with domain tags — cross-team visibility

Each file is a standalone artifact. Everyone leaves the session with a doc they own, not a monolith no one does.

Optionally pressure-test the outputs before moving on:

/productReview    # Founder/product lens: is this the right thing to build?
/archReview       # Engineering lens: is this the right way to build it?

Stage 3 — Design System & Mockups

/design-analyze   # Extract design tokens from reference sites (web or iOS)
/design-language  # Define brand personality and aesthetic direction
/design-mockup    # Generate HTML or SwiftUI mockup from design language
/design-refine    # Agents self-critique and iterate against the design language

Human in the loop: After the initial mockup is generated, agents enter a self-critique loop — evaluating whether the mockup faithfully reflects the established design language, identifying deviations, and refining autonomously. You step in at natural breakpoints: reviewing the current state, directing emphasis ("make the data table the focus, not the sidebar"), and deciding when the visual spec is ready to lock. You're the final arbiter of "good enough to build from," not a participant in every pixel decision.

These produce design-tokens.json, .impeccable.md, and a mockup.html (or SwiftUI file) that serve as the visual specification.

Stage 4 — Engineering Roadmap (GitHub Issues)

Create a multi-phase issue hierarchy directly from the officeHours output:

  1. Epic issue — paste the product vision, product.md, and the engineering.md approach section
  2. Task issues — one per entry in TASKS.md, each referencing the epic and embedding relevant context
  3. Attach mockups — link or embed the mockup screenshot so the visual spec lives in the issue

The officeHours MD files are ephemeral — once context is in GitHub issues, delete or ignore them. The issues become the canonical source of truth: product vision + design language reference + mockups all in one place, no local file sprawl.

Stage 5 — Ship

/review           # Multi-agent PR code review
/postReview       # Publish findings to GitHub as batched comments
/addressReview    # Implement fixes with parallel agents
/shipRelease      # Sync, test, push, open PR
/syncDocs         # Post-ship doc updater
/weeklyRetro      # Retrospective with shipping streaks

Human in the loop: Shipping is a loop, not a one-shot. The review agents surface issues and publish them to GitHub. You decide what to address before merge and what can be tracked as follow-ups. /addressReview implements the fixes in parallel; you review the diff. /shipRelease runs the gate checks — you approve the PR. The retro closes the loop: what shipped, what slipped, what to carry into next week.

Prerequisites

  • Node.js >= 20
  • Docker Desktop installed and running (required for Serena LSP)
  • Claude Code installed
  • GitHub CLI (gh) installed and authenticated (required by review skills)
  • jq installed (required by the statusline; brew install jq on macOS)
  • rtk — token-compressing CLI proxy (brew install rtk on macOS; installed automatically by setup.sh)
  • Python 3 + pip — required for headroom
  • headroom — context optimization layer (pip install "headroom-ai[all]"; installed automatically by setup.sh)

Contents

1. Skills & Config Archive

Extracted from ~/.claude/ for replication on any machine.

Skill Purpose
/review Multi-agent PR code review orchestrator
/postReview Publish review findings to GitHub as batched comments
/addressReview Implement review fixes with parallel agents
/enhancePrompt Context-aware prompt rewriter
/bootstrap Repo documentation generator (see below)
/rootCause 4-phase systematic debugging
/bugHunt Fix-and-verify loop with regression tests
/bugReport Structured bug report with health scores
/shipRelease Sync, test, push, open PR
/syncDocs Post-ship doc updater
/weeklyRetro Weekly retrospective with shipping streaks
/officeHours YC-style brainstorming → design doc
/productReview Founder/product lens plan review
/archReview Engineering architecture plan review
/design-analyze Platform dispatcher: extract design tokens from reference sites
/design-language Define brand personality and aesthetic direction
/design-evolve Platform dispatcher: merge new reference into design language
/design-mockup Platform dispatcher: generate mockup from design language
/design-implement Platform dispatcher: generate production code from mockup
/design-refine Dispatch Impeccable refinement commands
/design-verify Platform dispatcher: screenshot diff implementation vs mockup
/verify-app Platform-detecting Playwright/XcodeBuildMCP app verification
/verify-web Playwright browser verification of running web app
/verify-ios XcodeBuildMCP iOS simulator verification
/design-analyze-web Extract design tokens from web reference sites
/design-analyze-ios Extract design tokens from iOS app references
/design-evolve-web Merge new web reference into design language
/design-evolve-ios Merge new iOS reference into design language
/design-mockup-web Generate HTML mockup from design language
/design-mockup-ios Generate SwiftUI mockup from design language
/design-implement-web Generate production web code from mockup
/design-implement-ios Generate production SwiftUI code from mockup
/design-verify-web Screenshot diff web implementation vs mockup
/design-verify-ios XcodeBuildMCP visual diff iOS implementation vs mockup

Config files: config/settings.json, config/mcp.json, config/statusline.sh, config/hooks/

2. Statusline

config/statusline.sh is an adaptive two-line statusline for Claude Code sessions. It is installed to ~/.claude/statusline.sh and wired into settings.json automatically by setup.sh.

Columns (left → right, highest priority leftmost):

Column Description
5h Usage 5-hour rate-limit percentage + reset time
7d Usage 7-day rate-limit percentage + reset day
Context Color-coded bar + percentage of context window used
Model Active model name (trimmed)
Branch Current git branch
Cost Session cost in USD
Time Session duration
Cache Cache read hit rate
API API wait percentage
Lines Lines added/removed

Adaptive width tiers — columns drop automatically as the terminal narrows:

Tier Min width Columns shown
FULL 116 cols All columns, branch up to 15 chars
MEDIUM 101 cols No Lines; branch up to 12 chars
NARROW 78 cols No Lines/Cache/API; 7d % only; narrow context bar
COMPACT 65 cols 5h % only; narrow context bar; branch up to 10 chars
COMPACT-S < 65 cols Same as COMPACT but drops Time column

Terminal width is read from ~/.claude/terminal_width (written by the shell integration on every prompt and on SIGWINCH), which is the only reliable source because Claude Code runs the statusline in a subprocess where /dev/tty is inaccessible and $COLUMNS is 0.

Shell integration is installed by setup.sh to ~/.claude/shell-integration.sh and sourced from ~/.zshrc / ~/.bashrc. It keeps ~/.claude/terminal_width current and writes ~/.claude/shell_pid so resize events propagate mid-session via SIGWINCH.

3. Bootstrap Skill

Invocable via /bootstrap in any repo. Orchestrates documentation generation:

  • Detects which of 17 Pivot-pattern docs exist (BUSINESS_PLAN, ARCHITECTURE, ERD, etc.)
  • Generates missing docs adapted to the target repo's tech stack
  • Creates a trimmed CLAUDE.md (navigation doc only, under 80 lines) if none exists
  • Creates a .claude/rules/ directory with glob-scoped rule files inferred from the repo's structure
  • Handles bare repos, partially documented repos, and well-documented repos

4. MCP Bridge (Claude Code / Codex)

A TypeScript MCP server for bidirectional multi-agent communication.

MCP Tools (messaging):

  • send_context — Send task context + meta-prompt between agents
  • get_messages — Retrieve conversation history by UUID
  • get_unread — Check for unread messages (marks as read on retrieval)
  • assign_task — Assign tasks with domain and implementation details
  • report_status — Report back with feedback or completion

API Endpoints (messaging):

  • POST /messages/send — Send context between agents
  • GET /messages/conversation/:id — Retrieve conversation history
  • GET /messages/unread?recipient= — Fetch and mark-read unread messages
  • POST /tasks/assign — Assign a task with domain classification
  • GET /tasks/:id — Get a task by ID
  • GET /tasks/conversation/:id — Get all tasks for a conversation
  • POST /tasks/report — Report task status
  • GET /conversations — Paginated conversation summaries

Features:

  • SQLite store-and-forward (messages queue when recipient is offline)
  • Conversation continuity via UUID
  • Fastify REST API (port 3100) + MCP stdio server
  • Full end-to-end type safety with AppResult<T> pattern
  • Atomic transactions for multi-step operations

Setup

git clone https://github.com/joi-fairshare/agentic-workflow.git ~/repos/agentic-workflow
cd ~/repos/agentic-workflow
./setup.sh

The setup script:

  • Checks for jq and Docker (hard prerequisites — aborts with install instructions if missing)
  • Symlinks skills into ~/.claude/skills/
  • Copies config files (settings, MCP)
  • Installs safety hooks (block-destructive.sh, block-push-main.sh, detect-secrets.sh, rtk-rewrite.sh, git-context.sh) to ~/.claude/hooks/
  • Installs the statusline to ~/.claude/statusline.sh and wires statusLine into settings.json
  • Installs shell integration to ~/.claude/shell-integration.sh and sources it from ~/.zshrc / ~/.bashrc for terminal width sync
  • Installs and builds the MCP bridge
  • Builds Serena Docker images (base TS/Python image; opt-in C# extension)
  • Installs the serena-docker wrapper script to ~/.local/bin/
  • Registers agentic-bridge and serena MCP servers with Claude Code
  • Adds plugin marketplaces and installs plugins (github, superpowers, compound-engineering, playwright)
  • Registers xcodebuildmcp MCP server for iOS simulator automation
  • Installs rtk (Homebrew on macOS, install script on Linux) and wires rtk-rewrite.sh into the Bash hook chain for token-efficient command output
  • Installs headroom (pip install "headroom-ai[all]") and registers the headroom MCP server with Claude Code and Codex
  • Registers prism-mcp MCP server with Claude Code and Codex (persistent memory via prism-mcp-server, downloads on first use)

Start the bridge

cd mcp-bridge && npm start    # Fastify on http://127.0.0.1:3100

Environment Variables

Variable Default Description
PORT 3100 REST API port
HOST 127.0.0.1 Bind address (loopback only by default)
DB_PATH ./bridge.db SQLite database file path
ALLOW_REMOTE unset Set to 1 to allow non-loopback binding

Testing

Both packages enforce 100% coverage on all thresholds (statements, branches, functions, lines).

# MCP Bridge (Vitest, in-memory SQLite)
cd mcp-bridge
npm test                  # Run all tests (99 tests)
npm run test:watch        # Watch mode
npm run test:coverage     # Enforce 100% coverage thresholds

Test coverage spans unit tests (controllers, services, DB client, schemas, utilities) and integration tests (all REST routes via Fastify inject and MCP tool handlers).

Architecture

agentic-workflow/
├── .claude/
│   └── rules/                 # Glob-scoped domain rules (auto-loaded by Claude Code)
│       ├── bridge-services.md # AppResult, EventBus, MCP tools
│       ├── bridge-transport.md # Typed router, controllers, Zod schemas
│       ├── database.md        # SQLite schema, DbClient
│       ├── design.md          # Design pipeline, tokens, .impeccable.md
│       ├── hooks.md           # Hook protocols and installation
│       ├── mcp-servers.md     # MCP server usage rules (Serena, bridge, context7, etc.)
│       ├── skills.md          # Skill structure, preamble, pipeline, bootstrap
│       └── testing.md         # Test patterns, helpers, coverage policy
├── .serena/
│   └── project.yml            # Serena LSP per-repo config (TypeScript)
├── skills/                    # 35 Claude Code custom skills
│   ├── review/                # Multi-agent PR review
│   ├── postReview/            # GitHub comment publisher
│   ├── addressReview/         # Review fix implementer
│   └── enhancePrompt/         # Context-aware prompt rewriter
├── bootstrap/                 # Repo documentation generator skill
├── config/                    # Settings, MCP config, statusline script, and safety hooks
├── scripts/
│   └── serena-docker          # Wrapper script: mounts repo into Serena container
├── mcp-bridge/                # MCP bridge application
│   ├── src/
│   │   ├── application/       # AppResult<T>, EventBus, services (never throw)
│   │   ├── db/                # SQLite schema, client interface, transactions
│   │   ├── transport/         # Typed router, Zod schemas, controllers
│   │   ├── routes/            # Route factories (messages, tasks, conversations)
│   │   ├── server.ts          # Fastify server factory
│   │   ├── mcp.ts             # MCP stdio server (5 coordination tools)
│   │   └── index.ts           # REST API entry point
│   └── tests/                 # Vitest suite — unit + integration, 100% coverage
├── Dockerfile.serena           # Serena base image (TypeScript + Python LSPs)
├── Dockerfile.serena-csharp    # Serena C# extension image (opt-in)
└── setup.sh                   # One-command setup script

About

Portable Claude Code workflow toolkit: skills, config, repo bootstrapper, and MCP bridge for multi-agent communication

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

2 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages