Skip to content
BranchesTags
 
 

Repository files navigation

MCW - Managed Claude Workflow

A production-ready Claude Code workspace configuration with MCP server integrations, custom skills, and specialized agents for structured software delivery.

Features

  • MCP Server Integration: Pre-configured connections to Atlassian (Jira/Confluence), GitLab, Puppeteer, Chrome DevTools, and Planka
  • Custom Skills: /mcw for structured delivery workflow, /planka for task management
  • Specialized Agents: 25+ agents for architecture, security, debugging, code review, and more
  • Workflow Commands: E2E testing, refactoring, and documentation management
  • Multi-Stack Support: PHP/Symfony, TypeScript/React, NestJS, and more

Table of Contents

Prerequisites

Before you begin, ensure you have:

  • Claude Code or Claude Desktop installed and configured
  • Node.js 18+ (required for MCP servers) - verify with node --version
    • Chrome DevTools requires Node.js 20+
  • Git for version control
  • Active accounts for services you plan to integrate (optional):

Note: MCP servers are installed automatically via npx when first accessed - no manual installation needed.

Quick Start

Choose Your Installation Method

Method 1: Start a New Project with MCW ⭐ Recommended for new projects

Use MCW as your project foundation and build your application within it:

# Clone the repository
git clone https://github.com/your-username/mcw.git my-project
cd my-project

# Set up environment variables
cp .env.dist .env
# Edit .env with your API credentials

# Optional: Configure Planka
cp .planka.json.dist .planka.json
# Edit .planka.json with your board/list IDs

# Create your application structure (recommended)
mkdir -p api frontend
# Now build your app in api/ and frontend/ directories

Why this structure?

  • MCW provides the workspace configuration at the root
  • Your application code stays organized in subdirectories
  • All MCP integrations, skills, and agents work seamlessly
  • Easy to maintain and update MCW independently

Method 2: Add MCW to an Existing Project

Copy MCW configuration files into your existing codebase:

# From within your existing project directory
cd /path/to/your/existing/project

# Clone MCW temporarily
git clone https://github.com/your-username/mcw.git /tmp/mcw

# Copy configuration files
cp -r /tmp/mcw/.claude ./
cp /tmp/mcw/.env.dist ./.env
cp /tmp/mcw/.mcp.json ./
cp /tmp/mcw/.gitignore ./.gitignore  # Or merge with existing
cp -r /tmp/mcw/.claude/skills ./.claude/skills  # Optional: workflow skills

# Optional: Configure Planka
cp /tmp/mcw/.planka.json.dist ./.planka.json

# Clean up
rm -rf /tmp/mcw

# Edit .env with your API credentials
nano .env

Note: If you already have a .claude/ directory, merge the agents and skills selectively.

Configure MCP Servers

Edit .claude/settings.local.json to enable the MCP servers you want:

{
  "enabledMcpjsonServers": [
    "atlassian",
    "gitlab",
    "puppeteer",
    "chrome-devtools",
    "planka"
  ],
  "enableAllProjectMcpServers": true
}

Set Up Environment Variables

Edit your .env file with your API credentials:

Required environment variables by MCP server:

Atlassian (Jira & Confluence)

ATLASSIAN_SITE_URL="https://yourcompany.atlassian.net"
ATLASSIAN_USERNAME="your-email@company.com"
ATLASSIAN_API_TOKEN="your-api-token-here"

How to get your API token:

  1. Go to Atlassian API Tokens
  2. Create a new token with appropriate permissions
  3. Copy the token immediately (it won't be shown again)

Note: Jira uses /jira path and Confluence uses /wiki path on the same domain. No separate URL needed.

GitLab

GITLAB_URL="https://gitlab.com"
GITLAB_PERSONAL_ACCESS_TOKEN="your-gitlab-token"

How to get your GitLab token:

  1. Go to GitLab Access Tokens
  2. Create token with scopes: api, read_repository, write_repository
  3. Copy the token

Planka (Optional)

PLANKA_BASE_URL="https://planka.yourcompany.com"
PLANKA_AGENT_EMAIL="your-planka-email@company.com"
PLANKA_AGENT_PASSWORD="your-planka-password"

Configure Planka (Optional)

If using Planka for task management:

cp .planka.json.dist .planka.json

Edit .planka.json with your board and list IDs:

{
  "boards": {
    "your_board_name": {
      "boardId": "YOUR_BOARD_ID",
      "lists": {
        "backlog": "LIST_ID_FOR_BACKLOG",
        "discovery": "LIST_ID_FOR_DISCOVERY",
        "ready_to_dev": "LIST_ID_FOR_READY",
        "doing": "LIST_ID_FOR_IN_PROGRESS",
        "test": "LIST_ID_FOR_TESTING",
        "done": "LIST_ID_FOR_DONE"
      }
    }
  }
}

How to find your IDs:

  1. Open your Planka board in a browser
  2. Board ID is in the URL: https://planka.example.com/boards/{boardId}
  3. List IDs: Use /planka skill to list available boards and lists
  4. See PLANKA.md for detailed configuration guide

Verify Your Setup

Test that everything is configured correctly:

  1. Start Claude Code in your project directory:

    claude

  2. Check MCP Server Status:

    Type: What MCP servers are available?

    You should see: atlassian, gitlab, puppeteer, chrome-devtools, planka (if configured)

  3. Test a Simple Command:

    Try: Navigate to https://example.com using Puppeteer and take a screenshot

  4. Verify Environment Variables:

    # Check that .env is properly configured (values should not be empty)
grep -v '^#' .env | grep -v '^$'

  5. Test Skills:

    Try: /mcw --help
Try: /planka list boards

✅ Success indicators:

  • MCP servers appear in Claude's available tools
  • No authentication errors when using services
  • Skills execute without errors

❌ If something's wrong, see Troubleshooting section below.

Documentation

Comprehensive guides for each component:

MCP Server Integration Guides

  • Atlassian Integration - Jira and Confluence MCP server guide

    • Jira: Project management, issue tracking, sprint planning
    • Confluence: Wiki pages, documentation, knowledge base
    • JQL queries, ticket CRUD operations, page creation
    • Prerequisites: Atlassian Cloud account, API token

  • GitLab Integration - GitLab MCP server guide

    • Repository management and branch operations
    • Merge request creation and code review workflows
    • CI/CD pipeline monitoring and logs
    • Issue tracking and project management
    • Prerequisites: GitLab account, personal access token

  • Puppeteer Browser Automation - Puppeteer MCP server guide

    • Web scraping and data extraction
    • E2E test automation with Playwright integration
    • Screenshot and PDF generation
    • Form filling and web interaction
    • Prerequisites: Node.js 18+, Chrome/Chromium browser

  • Chrome DevTools - Chrome DevTools MCP server guide

    • Performance profiling and optimization
    • Network request inspection and debugging
    • Console log analysis and debugging
    • DOM manipulation and element inspection
    • Prerequisites: Node.js 20+, Chrome browser

  • Planka Task Management - Planka MCP server guide

    • Board and list management
    • Card creation and workflow automation
    • Task tracking and time management
    • Integration with /mcw structured delivery workflow
    • Prerequisites: Planka instance, user credentials

Workflow Documentation

💡 Quick Tip: Start with the Puppeteer guide for an easy verification that your MCP setup is working correctly.

Available Skills

Skills are slash commands that invoke specialized workflows.

/mcw - Structured Delivery Workflow

Automates the complete software delivery lifecycle with specialized agents for each phase.

When to use: Building new features from scratch with a structured, enterprise-grade process.

What it does:

  1. PRD Creation: pm-prd-architect agent writes detailed Product Requirements Document
  2. RFC Design: analyser-architect agent creates technical architecture (Request for Comments)
  3. Ticket Generation: dev-team-lead agent breaks work into actionable Planka cards
  4. Parallel Development: Specialized agents (frontend, backend, etc.) implement simultaneously
  5. Quality Gates: analyser-code-reviewer reviews all code before completion

Usage examples:

/mcw Add user authentication with OAuth 2.0 and JWT tokens
/mcw Build a real-time dashboard with WebSocket notifications
/mcw Implement Stripe payment integration with webhooks

Expected process: PRD → RFC → Tickets → Implementation → Review (15-30 minutes depending on complexity)

Output:

  • PRD.md - Product Requirements Document
  • RFC.md - Technical architecture and design decisions
  • Planka board populated with tickets
  • Implementation code across multiple files
  • Test coverage
  • Code review report with security analysis

/planka - Task Management

Manage Planka board tasks directly from Claude Code.

When to use: Creating, moving, and tracking work items without leaving your editor.

Capabilities:

  • Create cards with checklist tasks
  • Move cards through workflow stages (backlog → discovery → ready_to_dev → doing → test → done)
  • Add comments and labels
  • Track time with stopwatch
  • Query board state and card details

Usage examples:

/planka Create card "Add Stripe webhooks" in ready_to_dev
/planka Move card #123 to doing and start stopwatch
/planka Add comment to card #123 "Completed signature validation"
/planka List all cards in doing
/planka Get board summary with task counts

Integration: Works seamlessly with /mcw workflow - tickets created by /mcw appear in Planka automatically.

Available Workflows

Documented processes in the .claude/skills/ directory that guide common development tasks.

E2E Testing Workflow

File: .claude/skills/e2e/SKILL.md

Generate and run Playwright end-to-end tests for critical user journeys.

What it covers:

  • Test journey planning (login flows, checkout, user registration)
  • Playwright test generation with Page Object Model
  • Cross-browser testing (Chrome, Firefox, Safari)
  • Screenshot, video, and trace capture on failures
  • Flaky test detection and quarantine recommendations

When to use: Before merging features, for regression testing, validating production-critical flows

Safe Code Cleanup

File: .claude/skills/refactor-clean/SKILL.md

Identify and remove dead code with automated test verification.

What it covers:

  • Dead code analysis with knip, depcheck, ts-prune
  • Categorization by risk (SAFE, CAUTION, DANGER)
  • Test-driven deletion (run tests → delete code → verify tests pass)
  • Rollback on test failures

When to use: During refactoring sprints, before major releases, when reducing technical debt

Documentation Sync

File: .claude/skills/update-docs/SKILL.md

Generate documentation from source-of-truth files (package.json, .env.example).

What it covers:

  • Extract scripts from package.json into reference tables
  • Document environment variables from .env.example
  • Generate CONTRIB.md (development workflow, setup, testing)
  • Generate RUNBOOK.md (deployment, monitoring, troubleshooting)
  • Identify obsolete documentation (90+ days old)

When to use: After changing scripts, adding env variables, onboarding new team members

Specialized Agents

Located in .claude/agents/, these agents provide domain expertise for specific tasks.

Analysis Agents

  • analyser-architect - Software architecture and RFC design
  • analyser-code-reviewer - Code quality, security, and maintainability review
  • analyser-debugger - Root cause analysis and production debugging
  • analyser-security - Security threat modeling and vulnerability scanning
  • analyser-refactorer - Code quality improvement and technical debt reduction
  • analyser-documentation - Technical writing and knowledge transfer
  • analyser-devops - Infrastructure reliability and incident response
  • analyser-e2e - End-to-end test strategy and implementation

Development Agents

  • typescript-frontend - React, TypeScript, MUI frontend development
  • typescript-nestjs - NestJS backend API development
  • php-symfony - Symfony backend development
  • php-developer - PHP 8 best practices and standards
  • php-stan - PHPStan error resolution
  • php-cs - PHP coding standards enforcement
  • php-messenger - Symfony Messenger architecture
  • php-stripe-symfony-integration - Stripe payment integration for Symfony

Management Agents

  • pm-prd-architect - Product Requirements Document creation
  • dev-team-lead - Ticket management and team coordination
  • cto-tech-strategist - Technical strategy and architecture decisions
  • cpo-strategist - Product strategy and roadmap planning

Design Agents

  • figma-ux-ui-spec - UX/UI specifications from Figma designs
  • brand-guardian - Brand consistency and design system compliance
  • ui-designer - Interface design and component architecture

Usage Examples

Example 1: Complete Feature Development with /mcw

Scenario: Add Stripe payment integration to an e-commerce platform

You: /mcw Add Stripe payment integration with checkout, webhooks, and subscription management

Claude (pm-prd-architect):
📋 Creating Product Requirements Document...

[Asks clarifying questions about payment flows, error handling, webhook events]

✓ PRD.md created with:
  - User stories (guest checkout, subscription management, payment methods)
  - Acceptance criteria (PCI compliance, webhook reliability, error recovery)
  - Security requirements (token handling, webhook signature validation)
  - Edge cases (payment failures, duplicate charges, refunds)

Waiting for your approval: "PRD validated"

You: PRD validated

Claude (analyser-architect):
🏗️ Creating RFC based on PRD...

✓ RFC.md created with:
  - Architecture: Symfony backend + React frontend
  - API endpoints: POST /payments, POST /webhooks/stripe, GET /subscriptions
  - Database schema: payments, subscriptions, webhook_events tables
  - Error handling strategy: retry logic with exponential backoff
  - Testing approach: unit tests + Stripe test mode integration tests

Waiting for your approval: "RFC validated"

You: RFC validated

Claude (dev-team-lead):
🎫 Creating Planka tickets from RFC...

✓ Created 8 tickets in board "E-commerce Platform":
  1. [BACKEND] Create Stripe SDK integration service
  2. [BACKEND] Implement checkout API endpoint
  3. [BACKEND] Build webhook handler with signature validation
  4. [BACKEND] Add subscription management endpoints
  5. [FRONTEND] Create payment form component
  6. [FRONTEND] Add subscription UI dashboard
  7. [TESTS] Write Stripe integration tests
  8. [SECURITY] Conduct payment flow security audit

Claude (parallel execution):
🚀 Starting parallel implementation...

[typescript-nestjs agent]: Implementing backend services...
✓ Created src/stripe/stripe.service.ts
✓ Created src/payments/payments.controller.ts
✓ Created src/webhooks/stripe-webhook.controller.ts
✓ Added webhook signature validation

[typescript-frontend agent]: Implementing UI components...
✓ Created components/PaymentForm.tsx
✓ Created components/SubscriptionDashboard.tsx
✓ Added Stripe Elements integration

[analyser-code-reviewer agent]: Reviewing code...
✓ Security: Webhook signatures validated correctly
✓ Error handling: Proper try-catch and user feedback
⚠️  Warning: Add idempotency keys to prevent duplicate charges
✓ Tests: 87% coverage achieved

All tasks completed in 23 minutes.

Summary:
- 12 files created
- 8 Planka tickets completed
- 2 documentation files (PRD.md, RFC.md)
- Security audit passed with 1 recommendation

Time: ~25 minutes Output: Complete feature with documentation, tests, and security review

Example 2: Task Management with /planka

Scenario: Moving tickets through development workflow

You: /planka List cards in ready_to_dev

Claude:
📋 Cards in "Ready to Dev":

1. [CARD-123] Implement Stripe webhook handler
   Due: Tomorrow | Labels: backend, payments

2. [CARD-124] Add payment form UI component
   Due: This week | Labels: frontend, payments

3. [CARD-125] Write Stripe integration tests
   Due: This week | Labels: tests

You: I'm starting work on CARD-123

Claude:
✓ Moved "Implement Stripe webhook handler" to "Doing"
✓ Stopwatch started (tracking time for this card)

[3 hours later]

You: /planka Add comment to CARD-123 "Completed webhook signature validation and event processing"

Claude:
✓ Comment added to CARD-123

You: /planka Move CARD-123 to test and stop stopwatch

Claude:
✓ Moved "Implement Stripe webhook handler" to "Test"
✓ Stopwatch stopped (Total time: 3h 12m)
✓ Time logged to card

Benefit: Full task visibility and time tracking without leaving Claude Code

Example 3: E2E Testing with Playwright

Scenario: Test checkout flow before production deployment

You: Generate E2E tests for checkout flow: add product to cart, apply discount code, complete payment with Stripe

Claude (e2e-runner agent):
🧪 Generating Playwright test suite...

✓ Created tests/e2e/checkout-flow.spec.ts with:
  - Test: User can add product to cart
  - Test: Discount code applies correctly
  - Test: Payment form validation works
  - Test: Successful Stripe payment completes order
  - Test: Failed payment shows error message

🏃 Running tests with Playwright...

Test Results (Chromium):
  ✓ User can add product to cart (2.3s)
  ✓ Discount code applies correctly (1.8s)
  ✓ Payment form validation works (1.2s)
  ✗ Successful Stripe payment completes order (timeout after 30s)
  ✓ Failed payment shows error message (2.1s)

❌ Found issue in "Successful payment" test:
   Timeout waiting for element: [data-testid="order-confirmation"]

   Root cause analysis:
   - Webhook endpoint returned 500 error
   - Order status not updated from "pending" to "completed"

   Recommendation: Check webhook handler logs for errors

📸 Screenshots saved:
   - tests/screenshots/cart-with-product.png
   - tests/screenshots/payment-form.png
   - tests/screenshots/payment-timeout.png

🎬 Video recorded: tests/videos/checkout-flow-failed.webm
🔍 Trace file: tests/traces/checkout-flow-trace.zip

View full report: npx playwright show-report

Time: 3 minutes Output: Test suite + execution report + debugging artifacts

Example 4: Security Audit Before Deployment

Scenario: Pre-production security review of authentication system

You: @analyser-security Review the authentication system in src/auth/ for security vulnerabilities

Claude (analyser-security agent):
🔒 Security Threat Analysis Report

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔴 CRITICAL ISSUES (Must Fix Before Deploy)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. JWT tokens have no expiration time
   Location: src/auth/jwt.service.ts:23
   Risk: Stolen tokens remain valid indefinitely
   Fix:
   ```typescript
   sign(payload) {
     return jwt.sign(payload, SECRET, {
       expiresIn: '15m' // Access token
     });
   }

  1. Password reset tokens use sequential IDs Location: src/auth/password-reset.service.ts:45 Risk: Attackers can enumerate valid reset tokens Fix:

    const token = crypto.randomBytes(32).toString('hex');

  2. No rate limiting on login endpoint Location: src/auth/auth.controller.ts:18 Risk: Brute force attacks possible Fix:

    @UseGuards(ThrottlerGuard)
@Throttle(5, 900) // 5 attempts per 15 minutes
async login() { ... }

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🟡 WARNINGS (Should Fix Soon) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  1. Refresh tokens stored in localStorage Risk: XSS vulnerability can steal tokens Recommendation: Use httpOnly cookies

  2. Password requirements too weak Current: 6 characters minimum Recommendation: 12 chars, uppercase, lowercase, number, symbol

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✅ COMPLIANT ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Passwords hashed with bcrypt (cost: 12) ✓ SQL injection protected (parameterized queries) ✓ HTTPS enforced in production ✓ CORS configured correctly ✓ Input validation on all endpoints

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📝 Generated security patch files:

  • patches/001-jwt-expiration.patch
  • patches/002-secure-reset-tokens.patch
  • patches/003-rate-limiting.patch

Apply patches: git apply patches/*.patch


**Time**: 5 minutes
**Benefit**: Production-ready security before deployment

---

### Example 5: Web Scraping with Puppeteer

**Scenario**: Monitor competitor pricing daily

You: @puppeteer Navigate to https://competitor.com/pricing and extract all plan names, prices, and features

Claude: 🌐 Launching browser... ✓ Navigated to https://competitor.com/pricing ✓ Page loaded (2.3s)

📊 Extracted pricing data:

{ "plans": [ { "name": "Starter", "price": "$29/month", "features": [ "Up to 1,000 users", "5 GB storage", "Email support", "Basic analytics" ] }, { "name": "Professional", "price": "$99/month", "features": [ "Up to 10,000 users", "50 GB storage", "Priority support", "Advanced analytics", "API access" ] }, { "name": "Enterprise", "price": "Contact Sales", "features": [ "Unlimited users", "Unlimited storage", "24/7 dedicated support", "Custom integrations", "SLA guarantee" ] } ], "lastChecked": "2026-01-25T14:32:00Z" }

📸 Screenshot saved: competitor-pricing-2026-01-25.png 💾 Data saved: competitor-pricing-data.json

✓ Browser closed


**Time**: 30 seconds
**Output**: Structured JSON data + screenshot for verification

---

## Customization

### Add Your Own Agents

Create new agents in `.claude/agents/`:

```markdown
---
name: my-custom-agent
description: Specialized agent for [your domain]
---

# Agent Instructions

You are a specialist in [domain expertise].

Your responsibilities:
- [Responsibility 1]
- [Responsibility 2]

When users request [specific tasks], you should:
1. [Step 1]
2. [Step 2]

Use these tools:
- [Tool 1] for [purpose]
- [Tool 2] for [purpose]

Organization:

  • agents/analyser/ - Code analysis, debugging, security
  • agents/design/ - UX/UI, brand, Figma
  • agents/devops/ - Infrastructure, deployment, monitoring
  • agents/management/ - Product, project management
  • agents/php/ - PHP-specific development
  • agents/typescript/ - TypeScript-specific development

Add Your Own Skills

Create new skills in .claude/skills/:

---
name: my-skill
description: Custom workflow for [purpose]
---

# Skill Instructions

This skill performs [high-level description].

## When to Use
- [Scenario 1]
- [Scenario 2]

## Workflow
1. [Step 1]
2. [Step 2]
3. [Step 3]

## Usage Examples
\`\`\`
/my-skill [example input]
\`\`\`

Add Your Own Workflows

Create a new skill directory in .claude/skills/<skill-name>/SKILL.md:

mkdir -p .claude/skills/my-workflow
# .claude/skills/my-workflow/SKILL.md
---
name: my-workflow
description: Documentation for [workflow]
---

# Workflow Name

## Overview
[What this workflow accomplishes]

## When to Use
[Scenarios where this workflow is appropriate]

## Steps
1. [Step 1 with details]
2. [Step 2 with details]

## Example
[Real-world example with expected output]

Adapt Agents to Your Stack

Edit existing agents to match your technology stack:

Example: Customize typescript-frontend agent for Vue.js instead of React:

# Before (React-focused)
You are a React and TypeScript expert...

# After (Vue-focused)
You are a Vue 3 and TypeScript expert specializing in Composition API...

Example: Add your team's linting rules to analyser-code-reviewer:

Additional rules to enforce:
- Always use named exports (never default exports)
- Prefer async/await over .then() chains
- Database queries must have timeouts
- All API responses must include request IDs for tracing

Project Structure

mcw/
├── .claude/                    # Claude Code configuration
│   ├── agents/                 # Specialized AI agents
│   │   ├── analyser/          # Code analysis, debugging, security
│   │   ├── design/            # UX/UI, brand, Figma
│   │   ├── devops/            # Infrastructure, deployment
│   │   ├── management/        # Product, project management
│   │   ├── php/               # PHP/Symfony development
│   │   ├── product/           # Product requirements, PRDs
│   │   └── typescript/        # TypeScript/React/NestJS
│   ├── skills/                # Custom slash commands (skill-name/SKILL.md)
│   │   ├── mcw/SKILL.md       # /mcw structured delivery workflow
│   │   ├── planka/SKILL.md    # /planka task management
│   │   ├── e2e/SKILL.md       # /e2e E2E testing workflow
│   │   ├── refactor-clean/SKILL.md  # /refactor-clean code cleanup
│   │   └── update-docs/SKILL.md     # /update-docs documentation sync
│   └── settings.local.json    # MCP server configuration
│
├── .mcp.json                   # MCP server definitions
├── .env.dist                   # Environment variables template
├── .env                        # Your credentials (gitignored)
├── .planka.json.dist          # Planka configuration template
├── .planka.json               # Your Planka config (gitignored)
├── .gitignore                 # Ignore sensitive files
│
├── ATLASSIAN.md               # Jira/Confluence integration guide
├── GITLAB.md                  # GitLab integration guide
├── PUPPETEER.md               # Puppeteer automation guide
├── CHROME-DEV-TOOLS.md        # Chrome DevTools guide
├── PLANKA.md                  # Planka task management guide
└── README.md                  # This file
│
└── [YOUR APPLICATION]          # Your project code
    ├── api/                    # Backend code (recommended)
    ├── frontend/               # Frontend code (recommended)
    └── ...                     # Other project files

Design Philosophy:

  • MCW files at root provide workspace configuration
  • Your application code lives in subdirectories (api/, frontend/, etc.)
  • Configuration is modular and easy to update
  • Sensitive files (.env, .planka.json) are gitignored

Best Practices

Development Workflow

  1. Always start with /mcw for new features

    • Ensures PRD → RFC → Implementation → Review cycle
    • Documents requirements and architecture decisions
    • Provides quality gates before code review

  2. Use specialized agents for their domain expertise

    • Don't ask generic questions - target the right agent
    • Example: @analyser-security for security review, not generic Claude

  3. Run E2E tests before merging

    • Reference .claude/skills/e2e/SKILL.md for test generation
    • Critical flows must have E2E coverage
    • Review test artifacts (screenshots, traces) on failures

  4. Code review is mandatory

    • analyser-code-reviewer must review all code changes
    • Address security warnings before deploying
    • Never skip review for "small changes"

  5. Track all work in Planka

    • Use /planka to create cards from conversations
    • Move cards through workflow stages
    • Provides audit trail and team visibility

Security & Configuration

  1. Never commit .env or .planka.json

    • These contain sensitive credentials
    • Verify .gitignore includes these files
    • Use .dist templates for team sharing

  2. Rotate API tokens regularly

    • Quarterly rotation recommended
    • Use tokens with minimal required permissions
    • Revoke old tokens immediately

  3. Use minimal MCP server permissions

    • Only enable servers you actively use
    • Review what data each server can access
    • Disable unused servers in settings.local.json

  4. Review agent access carefully

    • Agents have access to your codebase
    • Agents can call external APIs (Jira, GitLab, etc.)
    • Understand what each agent can do before using it

  5. Environment variable security

    • Never hardcode credentials in code
    • Use .env for local development only
    • Use secure secret management in production (AWS Secrets Manager, etc.)

Agent Usage

  1. Choose the right agent for the task:

    • analyser-architect → Design decisions, RFC creation
    • analyser-debugger → Production bugs, root cause analysis
    • analyser-security → Security audits, vulnerability scanning
    • typescript-frontend → React/Vue UI work
    • typescript-nestjs → NestJS backend APIs
    • php-symfony → Symfony backend development
    • pm-prd-architect → Product requirements, user stories

  2. Customize agents for your tech stack:

    • Add framework-specific linting rules
    • Include your team's coding standards
    • Reference your architecture patterns
    • Add company-specific security requirements

  3. Provide context to agents:

    • Reference relevant files: "Review src/auth/jwt.service.ts"
    • Describe expected behavior: "JWT tokens should expire after 15 minutes"
    • Mention constraints: "Must work with PostgreSQL 14"

Troubleshooting

  1. MCP server not responding?

    • Check .env variables are set correctly
    • Verify Node.js version: node --version (18+ required, 20+ for Chrome DevTools)
    • Check network access to external services
    • Restart Claude Code to reload configuration
    • Enable server in .claude/settings.local.json

  2. Skill not working?

    • Verify .planka.json exists (for /planka skill)
    • Check agent files exist in .claude/agents/
    • Review skill file in .claude/skills/ for requirements
    • Check Claude Code output for error messages

  3. Authentication errors?

    • Verify API tokens are not expired
    • Check token has correct permissions (scopes)
    • Ensure URLs are correct (no trailing slashes)
    • Test credentials manually in browser or Postman

  4. Agent not behaving correctly?

    • Read the agent file in .claude/agents/ to understand its purpose
    • Provide more specific instructions
    • Reference specific files or code sections
    • Try a different agent if task doesn't match agent's expertise

  5. Performance issues?

    • Disable unused MCP servers
    • Close unused browser instances (Puppeteer, Chrome DevTools)
    • Clear Claude Code cache if responses are slow
    • Check system resources (RAM, CPU)

Still having issues? See the detailed troubleshooting sections in:

Contributing

This is a generic, reusable configuration designed to help developers build software more efficiently with Claude Code.

Ways to contribute:

  • Report issues: Found a bug or unclear documentation? Open an issue
  • Share agents: Created a useful agent? Submit a PR to add it to the collection
  • Improve documentation: Found a typo or want to clarify something? Submit a PR
  • Share workflows: Discovered an effective workflow? Document it in .claude/skills/

Guidelines:

  • Keep all content generic and project-agnostic
  • Follow existing naming conventions and file structure
  • Test agents and workflows before submitting
  • Update relevant documentation when adding new features

Troubleshooting

Common Issues

MCP Server Not Available

Symptoms: Claude doesn't recognize MCP server tools (e.g., Puppeteer, GitLab commands don't work)

Solutions:

  1. Verify server is enabled in .claude/settings.local.json:

    {
  "enabledMcpjsonServers": ["atlassian", "gitlab", "puppeteer", "chrome-devtools", "planka"],
  "enableAllProjectMcpServers": true
}

  2. Check .mcp.json configuration exists and is valid JSON

  3. Restart Claude Code completely

  4. Verify Node.js version: node --version (must be 18+ for most servers, 20+ for Chrome DevTools)

Authentication Errors

Symptoms: "401 Unauthorized", "403 Forbidden", "Invalid credentials"

Solutions:

  1. Verify .env file exists and contains credentials:

    cat .env | grep -v '^#' | grep -v '^$'

  2. Check API tokens are valid and not expired:

  3. Verify token permissions/scopes are sufficient:

    • GitLab needs: api, read_repository, write_repository
    • Atlassian needs: Read/write access to Jira and Confluence

  4. Check URLs are correct (no typos, correct protocol https://)

  5. Test credentials manually:

    # Test GitLab
curl -H "PRIVATE-TOKEN: your-token" https://gitlab.com/api/v4/user

# Test Atlassian
curl -u email@example.com:your-token https://yourcompany.atlassian.net/rest/api/3/myself

Planka Configuration Issues

Symptoms: /planka skill errors, "Board not found", "List not found"

Solutions:

  1. Verify .planka.json exists and has correct structure:

    {
  "boards": {
    "your_board_name": {
      "boardId": "...",
      "lists": {
        "backlog": "...",
        "doing": "..."
      }
    }
  }
}

  2. Find your board and list IDs:

    • Open Planka in browser
    • Board ID is in URL: https://planka.example.com/boards/{boardId}
    • Use /planka skill: "List all available boards" to get IDs

  3. Check Planka credentials in .env:

    PLANKA_BASE_URL="https://your-planka-instance.com"
PLANKA_AGENT_EMAIL="your-email@company.com"
PLANKA_AGENT_PASSWORD="your-password"

  4. Test Planka connection:

    Ask Claude: "List all Planka boards"

Node.js Version Issues

Symptoms: "Unsupported Node.js version", MCP server fails to start

Solutions:

  1. Check current version:

    node --version

  2. Upgrade Node.js:

    # Using nvm (recommended)
nvm install 20
nvm use 20
nvm alias default 20

# Or download from nodejs.org

  3. Verify after upgrade:

    node --version  # Should show v20.x.x or higher

Requirements:

  • Minimum: Node.js 18+
  • Chrome DevTools: Node.js 20+ (strict requirement)
  • Recommended: Node.js 20 LTS for best compatibility

Skills Not Working

Symptoms: /mcw or /planka commands not recognized

Solutions:

  1. Verify skill files exist:

    ls -la .claude/skills/
# Should show: mcw.md, planka.md

  2. Check skill file format (must have frontmatter):

    ---
name: skill-name
description: What it does
---

# Skill content...

  3. Restart Claude Code to reload skills

  4. Try running skill directly:

    /mcw --help
/planka --help

Agents Not Behaving Correctly

Symptoms: Agent gives generic responses, doesn't follow domain expertise

Solutions:

  1. Verify agent file exists:

    ls -la .claude/agents/analyser/
ls -la .claude/agents/typescript/

  2. Use correct agent invocation:

    @analyser-security Review authentication code
@typescript-frontend Create login form component

  3. Provide specific context:

    BAD:  "Review my code"
GOOD: "@analyser-security Review src/auth/jwt.service.ts for security vulnerabilities"

  4. Check if agent has required tools access

Performance Issues

Symptoms: Slow responses, high memory usage, timeouts

Solutions:

  1. Disable unused MCP servers in .claude/settings.local.json:

    {
  "enabledMcpjsonServers": ["puppeteer", "planka"],  // Only enable what you use
  "enableAllProjectMcpServers": true
}

  2. Close browser instances:

    # Check for lingering Chrome/Chromium processes
ps aux | grep -i chrome
ps aux | grep -i chromium

# Kill if needed
pkill -f chrome

  3. Clear Claude Code cache:

    rm -rf ~/.claude/cache/*

  4. Check system resources:

    # macOS
top -o MEM

# Linux
htop

Documentation Links Broken

Symptoms: Links to ATLASSIAN.md, GITLAB.md, etc. don't work

Solutions:

  1. Verify documentation files exist:

    ls -la *.md
# Should show: ATLASSIAN.md, GITLAB.md, PUPPETEER.md, CHROME-DEV-TOOLS.md, PLANKA.md

  2. Check file names match exactly (case-sensitive on Linux/macOS)

  3. Re-read README to find correct section links

Getting More Help

If you're still experiencing issues:

  1. Check detailed documentation:

  2. Review Claude Code documentation:

  3. Check MCP protocol documentation:

  4. Report issues:

License

Open source - use freely in your projects. Contributions welcome.

Built with ❤️ for developers who want to work smarter, not harder.

About

MCW - Managed Claude Workflow

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors