GitHub - andybraren/workflows: People and teams are unique. Give them a single, schema'd, versioned file to express the entirety of their SDLC preferences.

OOTB Workflow Templates

Out-of-the-box workflow templates for the Ambient Code Platform (vTeam). These workflows provide structured processes for AI agents to follow when working on complex tasks.

Overview

Workflows are Git repositories containing scripts, templates, agent configurations, and slash commands that guide Claude and other AI agents through multi-step processes. They help maintain consistency, quality, and best practices across your development workflow.

Available Workflows

Spec Kit Workflow (Default)

A comprehensive workflow for planning and implementing features using a specification-first approach.

Default Configuration:

Repository: https://github.com/Gkrumbach07/spec-kit-template.git
Branch: main
Path: workflows/spec-kit

Note: These defaults can be overridden via environment variables in the ACP backend deployment. See Configuration section below.

Structure:

workflows/default/
├── .specify/               # Workflow configuration
│   ├── scripts/           # Automation scripts
│   │   └── bash/         # Shell scripts for workflow steps
│   ├── templates/        # Document templates
│   │   ├── spec-template.md
│   │   ├── plan-template.md
│   │   ├── tasks-template.md
│   │   └── checklist-template.md
│   └── memory/           # Workflow knowledge base
│       └── constitution.md
└── .claude/              # Claude AI configuration
    ├── agents/           # Agent personas and instructions
    │   ├── archie-architect.md
    │   ├── parker-product_manager.md
    │   ├── stella-staff_engineer.md
    │   └── [20+ other agents]
    └── commands/         # Slash commands
        ├── /specify.md   # Create feature specifications
        ├── /plan.md      # Generate implementation plans
        ├── /tasks.md     # Break down into tasks
        └── /implement.md # Execute implementation

Workflow Phases:

Specify (/specify) - Create detailed feature specifications
Plan (/plan) - Generate technical implementation plans
Tasks (/tasks) - Break down plans into actionable tasks
Implement (/implement) - Execute the implementation
Analyze (/analyze) - Review and analyze outcomes

Best For:

Feature development
Complex implementations
Teams needing structured planning
Documentation-first approaches

Bug Fix Workflow (Coming Soon)

A streamlined workflow optimized for bug triage, reproduction, and fixes.

Planned Features:

Bug analysis and reproduction
Root cause identification
Fix implementation and validation
Regression test generation

Using Workflows in ACP

1. Via Session UI

When creating or working with a session:

Navigate to your session detail page
Open the Workflows accordion
Select a workflow:
- Spec Kit Workflow (OOTB) - The default specification workflow
- Bug Fix Workflow - (Coming soon)
- Custom Workflow... - Load your own workflow

The workflow will be cloned into your session's workspace and set as Claude's working directory.

2. Via API

POST /api/projects/{project}/agentic-sessions/{session}/workflow

{
  "gitUrl": "https://github.com/Gkrumbach07/spec-kit-template.git",
  "branch": "main",
  "path": "workflows/spec-kit"
}

3. Via Session Creation

Workflows can be pre-configured when creating sessions through automation or templates.

Workspace Structure

When a workflow is activated, your session workspace is organized as:

/workspace/sessions/{session-name}/
├── workflows/
│   ├── default/           # Empty unless workflow selected
│   └── spec-kit/          # Active workflow (when selected)
│       ├── .specify/      # Scripts, templates, memory
│       └── .claude/       # Agents and commands
└── artifacts/             # Output directory for generated files
    ├── spec/             # Generated specifications
    ├── plans/            # Implementation plans
    ├── tasks/            # Task breakdowns
    └── implementation/   # Code and artifacts

Key Concepts:

Working Directory: Claude works from workflows/{workflow-name}/
Artifacts Directory: All outputs go to artifacts/ (kept separate from workflow logic)
Workflow Switching: You can switch workflows mid-session without losing your artifacts

Creating Custom Workflows

Basic Structure

my-workflow/
├── .specify/              # (Optional) Specify framework integration
│   ├── scripts/
│   ├── templates/
│   └── memory/
├── .claude/               # (Optional) Claude-specific config
│   ├── agents/
│   └── commands/
└── README.md             # Workflow documentation

Requirements

Git Repository: Must be accessible via HTTPS or SSH
Branch: Specify which branch to use (default: main)
Path: Optionally specify a subdirectory within the repo

Best Practices

Keep workflows focused - One workflow per process type
Document commands - Provide clear instructions for each slash command
Include templates - Help agents maintain consistency
Version control - Use branches for workflow versions
Test iteratively - Validate workflows in real sessions

Example: Minimal Custom Workflow

# Create a new workflow repo
mkdir my-custom-workflow
cd my-custom-workflow
git init

# Add Claude commands
mkdir -p .claude/commands
cat > .claude/commands/review.md << 'EOF'
# /review - Code Review

Review the code in the artifacts directory:
1. Check for common issues
2. Verify best practices
3. Suggest improvements
4. Document findings in artifacts/review.md
EOF

# Commit and push
git add .
git commit -m "Initial workflow"
git remote add origin https://github.com/your-org/my-custom-workflow.git
git push -u origin main

Load it in ACP:

Select "Custom Workflow..." in the UI
Enter Git URL: https://github.com/your-org/my-custom-workflow.git
Branch: main
Path: (leave empty if workflow is at repo root)
Click "Load Workflow"

Workflow Development Guide

Agent Personas

Agents provide specialized expertise and perspectives. Each agent should have:

# Agent Name - Role

## Expertise
- Key area 1
- Key area 2

## Responsibilities
- What this agent does
- When to invoke this agent

## Communication Style
- How this agent communicates

Slash Commands

Commands guide Claude through specific tasks:

# /command-name - Short Description

## Purpose
What this command accomplishes

## Prerequisites
- File or state required before running

## Process
1. Step one
2. Step two
3. Step three

## Output
- What files/artifacts are created
- Where they are stored (always in artifacts/)

Templates

Provide structure for consistency:

# [Template Name]

## Section 1
Instructions for this section...

## Section 2
Instructions for this section...

Configuration

Environment Variables

The ACP backend supports configuring OOTB workflows via environment variables. This allows organizations to fork and customize workflows without changing code.

Spec Kit Workflow:

OOTB_SPEC_KIT_REPO - Git repository URL (default: https://github.com/Gkrumbach07/spec-kit-template.git)
OOTB_SPEC_KIT_BRANCH - Branch to use (default: main)
OOTB_SPEC_KIT_PATH - Path within repository (default: workflows/spec-kit)

Bug Fix Workflow:

OOTB_BUG_FIX_REPO - Git repository URL (required to enable)
OOTB_BUG_FIX_BRANCH - Branch to use (default: main)
OOTB_BUG_FIX_PATH - Path within repository (optional)

Example Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend
spec:
  template:
    spec:
      containers:
      - name: backend
        env:
        - name: OOTB_SPEC_KIT_REPO
          value: "https://github.com/your-org/custom-spec-kit.git"
        - name: OOTB_SPEC_KIT_BRANCH
          value: "production"

Backend API

The backend provides a public endpoint to list available OOTB workflows:

GET /api/workflows/ootb

Response:
{
  "workflows": [
    {
      "id": "spec-kit",
      "name": "Spec Kit Workflow",
      "description": "Comprehensive workflow for planning and implementing features...",
      "gitUrl": "https://github.com/Gkrumbach07/spec-kit-template.git",
      "branch": "main",
      "path": "workflows/spec-kit",
      "enabled": true
    },
    {
      "id": "bug-fix",
      "name": "Bug Fix Workflow",
      "description": "Streamlined workflow for bug triage...",
      "gitUrl": "",
      "branch": "main",
      "path": "",
      "enabled": false
    }
  ]
}

The frontend automatically fetches and displays configured workflows.

Troubleshooting

Workflow Not Cloning

Check URL: Ensure the Git URL is accessible
Check Branch: Verify the branch exists
Check Permissions: Private repos need authentication configured

Commands Not Working

Check Path: Ensure .claude/commands/ directory exists
Check Format: Commands must be markdown files
Check Session: Workflow must be activated in the session

Artifacts in Wrong Location

Workflow scripts should always write to /workspace/artifacts/
Check that scripts use absolute paths or $WORKSPACE/artifacts/
The workflows directory is for logic only, not outputs

Contributing

To contribute a new OOTB workflow:

Fork this repository
Create a new directory under workflows/
Follow the structure guidelines above
Submit a pull request with documentation
Include example usage and test results

Support

Documentation: ACP User Guide
Issues: GitHub Issues
Discussions: GitHub Discussions

License

This repository and all OOTB workflows are provided under the MIT License. See LICENSE file for details.

Repository: Gkrumbach07/spec-kit-template
Default Workflow: Spec Kit (workflows/spec-kit)
Platform: Ambient Code Platform (vTeam)