From ee3f44e910d2d8a5fdd511640eaa5a169d163199 Mon Sep 17 00:00:00 2001
From: Ambient Code Bot <bot@ambient-code.local>
Date: Fri, 28 Nov 2025 15:04:59 +0000
Subject: [PATCH] docs: update workflow documentation to reflect production
 status
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Mark all workflows (spec-kit, bugfix, template) as production-ready
- Update repository references from Gkrumbach07 to ambient-code org
- Add comprehensive Workflow Development Guide
- Document platform agent integration patterns
- Create README for spec-kit workflow
- Update template-workflow to clarify agent usage
- Update workspace structure and configuration examples
- Document future platform integration plans

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md                             | 150 ++++++++------
 WORKFLOW_DEVELOPMENT_GUIDE.md         | 284 ++++++++++++++++++++++++++
 workflows/spec-kit/README.md          | 209 +++++++++++++++++++
 workflows/template-workflow/README.md |  53 ++---
 4 files changed, 607 insertions(+), 89 deletions(-)
 create mode 100644 WORKFLOW_DEVELOPMENT_GUIDE.md
 create mode 100644 workflows/spec-kit/README.md

diff --git a/README.md b/README.md
index 658a4d3..244ba5e 100644
--- a/README.md
+++ b/README.md
@@ -8,16 +8,13 @@ Workflows are Git repositories containing scripts, templates, agent configuratio
 
 ## Available Workflows
 
-### Spec Kit Workflow (Default)
+### Spec Kit Workflow
 
 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`
+**Status:** Production Ready
 
-*Note: These defaults can be overridden via environment variables in the ACP backend deployment. See Configuration section below.*
+**Location:** `workflows/spec-kit`
 
 **Structure:**
 ```
@@ -60,15 +57,41 @@ workflows/default/
 - Teams needing structured planning
 - Documentation-first approaches
 
-### Bug Fix Workflow (Coming Soon)
+### Template Workflow
 
-A streamlined workflow optimized for bug triage, reproduction, and fixes.
+A comprehensive, self-contained template demonstrating all available configuration options for creating custom ACP workflows.
 
-**Planned Features:**
-- Bug analysis and reproduction
-- Root cause identification
-- Fix implementation and validation
-- Regression test generation
+**Status:** Production Ready
+
+**Location:** `workflows/template-workflow`
+
+**Features:**
+- Fully documented `ambient.json` with inline comments
+- Example slash commands demonstrating workflow phases
+- Sample agent personas for different roles
+- Complete field reference documentation
+- Best practices and usage patterns
+
+**Best For:**
+- Creating custom workflows
+- Learning workflow structure
+- Understanding configuration options
+- Starting point for new workflow types
+
+### Bug Fix Workflow
+
+A systematic workflow for analyzing, fixing, and verifying software bugs with comprehensive testing and documentation.
+
+**Status:** Production Ready
+
+**Location:** `workflows/bugfix`
+
+**Features:**
+- Systematic bug reproduction and documentation
+- Root cause analysis and impact assessment
+- Fix implementation following best practices
+- Comprehensive testing and regression test creation
+- Complete documentation and release notes generation
 
 ## Using Workflows in ACP
 
@@ -79,9 +102,10 @@ When creating or working with a session:
 1. Navigate to your session detail page
 2. Open the **Workflows** accordion
 3. Select a workflow:
-   - **Spec Kit Workflow (OOTB)** - The default specification workflow
-   - **Bug Fix Workflow** - (Coming soon)
-   - **Custom Workflow...** - Load your own workflow
+   - **Spec Kit Workflow** - Specification-driven feature development
+   - **Bug Fix Workflow** - Systematic bug resolution
+   - **Template Workflow** - Starting point for custom workflows
+   - **Custom Workflow...** - Load your own workflow from any Git repository
 
 The workflow will be cloned into your session's workspace and set as Claude's working directory.
 
@@ -91,7 +115,7 @@ The workflow will be cloned into your session's workspace and set as Claude's wo
 POST /api/projects/{project}/agentic-sessions/{session}/workflow
 
 {
-  "gitUrl": "https://github.com/Gkrumbach07/spec-kit-template.git",
+  "gitUrl": "https://github.com/ambient-code/workflows.git",
   "branch": "main",
   "path": "workflows/spec-kit"
 }
@@ -108,15 +132,19 @@ 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
+│   ├── spec-kit/          # Spec Kit workflow (when selected)
+│   │   ├── .specify/      # Scripts, templates, memory
+│   │   └── .claude/       # Agents and commands
+│   ├── bugfix/            # Bug Fix workflow (when selected)
+│   │   ├── .ambient/      # Workflow configuration
+│   │   └── .claude/       # Agents and commands
+│   └── template-workflow/ # Template workflow (when selected)
+│       ├── .ambient/      # Workflow configuration
 │       └── .claude/       # Agents and commands
 └── artifacts/             # Output directory for generated files
-    ├── spec/             # Generated specifications
-    ├── plans/            # Implementation plans
-    ├── tasks/            # Task breakdowns
-    └── implementation/   # Code and artifacts
+    ├── specs/            # Feature specifications (spec-kit)
+    ├── bugfix/           # Bug fix artifacts (bugfix workflow)
+    └── [custom]/         # Custom workflow outputs
 ```
 
 **Key Concepts:**
@@ -127,6 +155,8 @@ When a workflow is activated, your session workspace is organized as:
 
 ## Creating Custom Workflows
 
+**Quick Start:** See the [Workflow Development Guide](WORKFLOW_DEVELOPMENT_GUIDE.md) for a complete guide to creating custom workflows.
+
 ### Basic Structure
 
 ```
@@ -249,41 +279,24 @@ Instructions for this section...
 
 ## Configuration
 
-### Environment Variables
+### Future Platform Integration
 
-The ACP backend supports configuring OOTB workflows via environment variables. This allows organizations to fork and customize workflows without changing code.
+The Ambient Code Platform will eventually point to this repository (`https://github.com/ambient-code/workflows`) as the official source for OOTB workflows.
 
-**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`)
+### Environment Variables (Future)
 
-**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)
+Organizations will be able to configure OOTB workflows via environment variables in the ACP backend deployment, allowing customization without code changes.
 
-**Example Deployment:**
+**Planned Configuration:**
 ```yaml
-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"
+# Future ACP backend environment variables
+OOTB_WORKFLOWS_REPO: "https://github.com/ambient-code/workflows.git"
+OOTB_WORKFLOWS_BRANCH: "main"
 ```
 
-### Backend API
+### Backend API (Future)
 
-The backend provides a public endpoint to list available OOTB workflows:
+The backend will provide a public endpoint to list available OOTB workflows:
 
 ```bash
 GET /api/workflows/ootb
@@ -295,25 +308,34 @@ Response:
       "id": "spec-kit",
       "name": "Spec Kit Workflow",
       "description": "Comprehensive workflow for planning and implementing features...",
-      "gitUrl": "https://github.com/Gkrumbach07/spec-kit-template.git",
+      "gitUrl": "https://github.com/ambient-code/workflows.git",
       "branch": "main",
       "path": "workflows/spec-kit",
       "enabled": true
     },
     {
-      "id": "bug-fix",
+      "id": "bugfix",
       "name": "Bug Fix Workflow",
-      "description": "Streamlined workflow for bug triage...",
-      "gitUrl": "",
+      "description": "Systematic workflow for bug resolution...",
+      "gitUrl": "https://github.com/ambient-code/workflows.git",
       "branch": "main",
-      "path": "",
-      "enabled": false
+      "path": "workflows/bugfix",
+      "enabled": true
+    },
+    {
+      "id": "template-workflow",
+      "name": "Template Workflow",
+      "description": "Starting point for custom workflows...",
+      "gitUrl": "https://github.com/ambient-code/workflows.git",
+      "branch": "main",
+      "path": "workflows/template-workflow",
+      "enabled": true
     }
   ]
 }
 ```
 
-The frontend automatically fetches and displays configured workflows.
+The frontend will automatically fetch and display configured workflows.
 
 ## Troubleshooting
 
@@ -347,9 +369,9 @@ To contribute a new OOTB workflow:
 
 ## Support
 
-- **Documentation**: [ACP User Guide](https://ambient-code.github.io/vteam)
-- **Issues**: [GitHub Issues](https://github.com/Gkrumbach07/spec-kit-template/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/Gkrumbach07/spec-kit-template/discussions)
+- **Documentation**: [ACP User Guide](https://ambient-code.github.io/platform)
+- **Issues**: [GitHub Issues](https://github.com/ambient-code/workflows/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/ambient-code/workflows/discussions)
 
 ## License
 
@@ -357,7 +379,7 @@ This repository and all OOTB workflows are provided under the MIT License. See L
 
 ---
 
-**Repository:** [Gkrumbach07/spec-kit-template](https://github.com/Gkrumbach07/spec-kit-template)  
-**Default Workflow:** Spec Kit (`workflows/spec-kit`)  
-**Platform:** Ambient Code Platform (vTeam)
+**Repository:** [ambient-code/workflows](https://github.com/ambient-code/workflows)
+**Available Workflows:** Spec Kit, Bug Fix, Template
+**Platform:** Ambient Code Platform
 
diff --git a/WORKFLOW_DEVELOPMENT_GUIDE.md b/WORKFLOW_DEVELOPMENT_GUIDE.md
new file mode 100644
index 0000000..9f09b0b
--- /dev/null
+++ b/WORKFLOW_DEVELOPMENT_GUIDE.md
@@ -0,0 +1,284 @@
+# Workflow Development Guide
+
+Quick reference for creating and contributing custom workflows to the Ambient Code Platform.
+
+## Quick Start
+
+**Goal:** Create a custom workflow for your development process
+
+**Time:** 30-60 minutes
+
+**Starting Point:** Use the [template-workflow](workflows/template-workflow) as your foundation
+
+## Creating a Custom Workflow
+
+### 1. Copy the Template
+
+```bash
+cp -r workflows/template-workflow workflows/my-workflow
+cd workflows/my-workflow
+```
+
+### 2. Configure Your Workflow
+
+Edit `.ambient/ambient.json` (remove comments for production):
+
+```json
+{
+  "name": "My Workflow Name",
+  "description": "Brief description of what this workflow does and when to use it.",
+  "systemPrompt": "You are a [role] assistant. Follow these phases: [phase1 → phase2 → phase3]. Use /command1, /command2 commands. Create outputs in artifacts/my-workflow/",
+  "startupPrompt": "Welcome! I'll help you with [purpose]. Available commands: /command1, /command2. Run /command1 to begin.",
+  "results": {
+    "Output Type": "artifacts/my-workflow/**/*.md"
+  }
+}
+```
+
+**Required Fields:** name, description, systemPrompt, startupPrompt
+**Optional Fields:** results, version, tags, icon (see [FIELD_REFERENCE.md](workflows/template-workflow/FIELD_REFERENCE.md))
+
+### 3. Create Slash Commands
+
+Add commands in `.claude/commands/`:
+
+```markdown
+# /mycommand - Short description
+
+## Purpose
+What this command accomplishes
+
+## Prerequisites
+- Files or state needed before running
+
+## Process
+1. Step one
+2. Step two
+3. Step three
+
+## Output
+- Creates: artifacts/my-workflow/output.md
+- Updates: existing files if applicable
+
+## Usage
+/mycommand [optional-argument]
+```
+
+**Command Naming:** Use descriptive names (e.g., `/analyze`, `/implement`, `/verify`)
+
+### 4. Agent Usage (Optional)
+
+**Platform Agents Available:**
+- **Amber** - Codebase intelligence, pair programming
+- **Parker** - Product management, business value
+- **Stella** - Staff engineer, technical leadership
+- **Ryan** - UX research, user insights
+- **Steve** - UX design, visual design
+- **Terry** - Technical writing, documentation
+
+**When to Add Custom Agents:**
+- Workflow needs domain-specific expertise not covered by platform agents
+- Specialized role unique to your workflow
+
+**How to Add:**
+Create `.claude/agents/my-agent.md`:
+
+```markdown
+# Agent Name - Role
+
+## Expertise
+- Domain area 1
+- Domain area 2
+
+## Responsibilities
+- What this agent does
+- When to invoke
+
+## Communication Style
+- How this agent communicates
+```
+
+**Best Practice:** Use platform agents first, add custom agents only when necessary
+
+### 5. Test Your Workflow
+
+1. **Load in ACP Session:**
+   - Navigate to session detail page
+   - Select "Custom Workflow"
+   - Enter Git URL, branch, path
+
+2. **Test Commands:**
+   - Run each slash command
+   - Verify outputs in `artifacts/`
+   - Check for errors
+
+3. **Iterate:**
+   - Refine prompts based on behavior
+   - Update commands for clarity
+   - Adjust output paths
+
+## Contributing to OOTB Workflows
+
+Want to contribute your workflow to the official collection?
+
+### Prerequisites
+- Workflow tested in real sessions
+- Complete documentation (README.md)
+- Clear use case and value proposition
+
+### Submission Process
+
+1. **Fork Repository:**
+   ```bash
+   gh repo fork ambient-code/workflows
+   cd workflows
+   ```
+
+2. **Add Your Workflow:**
+   ```bash
+   cp -r your-workflow workflows/your-workflow-name
+   git add workflows/your-workflow-name
+   git commit -m "feat: add [workflow-name] workflow"
+   git push
+   ```
+
+3. **Submit Pull Request:**
+   - Include workflow description
+   - Example usage scenarios
+   - Test results from real sessions
+   - Screenshots/demos (optional)
+
+4. **PR Requirements:**
+   - [ ] Complete ambient.json configuration
+   - [ ] README.md with usage instructions
+   - [ ] At least 3 slash commands
+   - [ ] Tested in live ACP session
+   - [ ] No hardcoded secrets or sensitive data
+   - [ ] Clear artifact output locations
+
+## Best Practices
+
+### Configuration
+- **Start minimal:** Only required fields initially
+- **Clear prompts:** Specific instructions yield better results
+- **Output organization:** Use consistent artifact paths
+
+### Slash Commands
+- **Single purpose:** Each command does one thing well
+- **Sequential or standalone:** Design for both linear and flexible usage
+- **Clear documentation:** Prerequisites, process, outputs
+
+### Agent Usage
+- **Leverage platform agents:** Don't recreate what exists
+- **Proactive engagement:** Commands should invoke agents automatically when needed
+- **Clear orchestration:** Document when/why agents are invoked
+
+### Testing
+- **Real sessions:** Test in actual ACP environment
+- **Multiple scenarios:** Try different use cases
+- **User perspective:** Have others test your workflow
+
+## Common Patterns
+
+### Feature Development Workflow
+```
+/specify → /plan → /implement → /verify
+```
+Focus: New functionality, specifications, planning
+
+### Bug Fix Workflow
+```
+/reproduce → /diagnose → /fix → /test → /document
+```
+Focus: Issue resolution, root cause, verification
+
+### Code Review Workflow
+```
+/analyze → /review → /suggest → /validate
+```
+Focus: Quality, standards, best practices
+
+### Refactoring Workflow
+```
+/assess → /plan → /refactor → /verify
+```
+Focus: Code improvement, maintaining behavior
+
+## Troubleshooting
+
+**Workflow not loading?**
+- Check `.ambient/ambient.json` exists and is valid JSON
+- Remove all comment lines for production
+- Verify Git URL is accessible
+
+**Commands not working?**
+- Ensure files are in `.claude/commands/`
+- File names must match command names (`/mycommand` → `mycommand.md`)
+- Check markdown formatting
+
+**Outputs in wrong location?**
+- Always use `artifacts/` for outputs
+- Use absolute paths: `/workspace/artifacts/my-workflow/`
+- Check systemPrompt specifies correct paths
+
+**Agents not responding?**
+- Platform agents load automatically from platform context
+- Custom agents must be in `.claude/agents/`
+- Check agent file format and structure
+
+## Resources
+
+- **Template Workflow:** [workflows/template-workflow](workflows/template-workflow)
+- **Field Reference:** [FIELD_REFERENCE.md](workflows/template-workflow/FIELD_REFERENCE.md)
+- **Example Workflows:** [workflows/spec-kit](workflows/spec-kit), [workflows/bugfix](workflows/bugfix)
+- **Platform Agents:** [platform/agents](https://github.com/ambient-code/platform/tree/main/agents)
+- **Issues:** [github.com/ambient-code/workflows/issues](https://github.com/ambient-code/workflows/issues)
+
+## Quick Reference
+
+### Minimal Workflow Structure
+```
+my-workflow/
+├── .ambient/
+│   └── ambient.json          # Required: workflow config
+├── .claude/
+│   └── commands/             # Required: slash commands
+│       └── mycommand.md
+└── README.md                 # Recommended: documentation
+```
+
+### Standard Workflow Structure
+```
+my-workflow/
+├── .ambient/
+│   └── ambient.json
+├── .claude/
+│   ├── agents/               # Optional: custom agents
+│   │   └── specialist.md
+│   └── commands/             # Required: slash commands
+│       ├── init.md
+│       ├── execute.md
+│       └── verify.md
+├── scripts/                  # Optional: automation
+├── templates/                # Optional: document templates
+└── README.md
+```
+
+### Essential ambient.json
+```json
+{
+  "name": "Workflow Name",
+  "description": "What it does and when to use it.",
+  "systemPrompt": "You are a [role] assistant...",
+  "startupPrompt": "Welcome! Run /command to begin.",
+  "results": {
+    "Outputs": "artifacts/**/*.md"
+  }
+}
+```
+
+---
+
+**Ready to build?** Start with `workflows/template-workflow` and customize for your needs!
+
+**Questions?** Open an issue: [github.com/ambient-code/workflows/issues](https://github.com/ambient-code/workflows/issues)
diff --git a/workflows/spec-kit/README.md b/workflows/spec-kit/README.md
new file mode 100644
index 0000000..ee0c677
--- /dev/null
+++ b/workflows/spec-kit/README.md
@@ -0,0 +1,209 @@
+# Spec Kit Workflow
+
+Comprehensive specification-driven development workflow for feature planning, task breakdown, and implementation.
+
+## Overview
+
+The Spec Kit Workflow guides you through a structured approach to feature development:
+
+1. **Specify** - Create detailed feature specifications
+2. **Analyze** - Perform cross-artifact consistency analysis
+3. **Clarify** - Identify and resolve underspecified areas
+4. **Plan** - Generate technical implementation plans
+5. **Tasks** - Break down plans into actionable tasks
+6. **Implement** - Execute the implementation
+7. **Checklist** - Generate custom verification checklists
+
+## Quick Start
+
+### In an ACP Session
+
+1. Select "Spec Kit Workflow" from the workflows dropdown
+2. Wait for workspace initialization
+3. Run the initialization script: `./.specify/scripts/bash/init-workspace.sh`
+4. Start with `/speckit.specify [feature-description]`
+
+### Available Commands
+
+- `/speckit.specify` - Create or update feature specification
+- `/speckit.analyze` - Analyze consistency across spec, plan, and tasks
+- `/speckit.clarify` - Ask targeted clarification questions
+- `/speckit.plan` - Generate implementation plan
+- `/speckit.tasks` - Generate actionable task breakdown
+- `/speckit.implement` - Execute the implementation
+- `/speckit.checklist` - Generate custom verification checklist
+- `/speckit.constitution` - Create or update project constitution
+
+## Workflow Phases
+
+### 1. Specify (`/speckit.specify`)
+
+Creates a detailed feature specification from natural language description.
+
+**Input:** Feature description
+**Output:** `artifacts/specs/**/spec.md`
+
+### 2. Analyze (`/speckit.analyze`)
+
+Performs non-destructive cross-artifact analysis for consistency and quality.
+
+**Input:** Existing spec.md, plan.md, tasks.md
+**Output:** Analysis report with recommendations
+
+### 3. Clarify (`/speckit.clarify`)
+
+Identifies underspecified areas and asks up to 5 targeted clarification questions.
+
+**Input:** Current spec.md
+**Output:** Updated spec.md with clarifications
+
+### 4. Plan (`/speckit.plan`)
+
+Generates technical implementation plan using the plan template.
+
+**Input:** spec.md
+**Output:** `artifacts/specs/**/plan.md`
+
+### 5. Tasks (`/speckit.tasks`)
+
+Generates dependency-ordered, actionable task breakdown.
+
+**Input:** spec.md, plan.md
+**Output:** `artifacts/specs/**/tasks.md`
+
+### 6. Implement (`/speckit.implement`)
+
+Executes the implementation by processing all tasks in tasks.md.
+
+**Input:** tasks.md
+**Output:** Code changes, implementation artifacts
+
+### 7. Checklist (`/speckit.checklist`)
+
+Generates a custom verification checklist based on user requirements.
+
+**Input:** Feature requirements
+**Output:** Custom checklist
+
+## Agent Orchestration
+
+The Spec Kit Workflow includes agents for different roles and perspectives. These agents are invoked automatically as needed:
+
+**Engineering & Architecture:**
+- Archie (Architect), Stella (Staff Engineer), Emma (Engineering Manager), Lee (Team Lead), Taylor (Team Member), Neil (Test Engineer)
+
+**Product & Strategy:**
+- Parker (Product Manager), Olivia (Product Owner), Dan (Senior Director), Diego (Program Manager), Sam (Scrum Master), Jack (Delivery Owner)
+
+**UX & Design:**
+- Aria (UX Architect), Uma (UX Team Lead), Felix (UX Feature Lead), Steve (UX Designer), Ryan (UX Researcher), Phoenix (PxE Specialist)
+
+**Content & Documentation:**
+- Terry (Technical Writer), Tessa (Writing Manager), Casey (Content Strategist)
+
+**Note:** Platform agents (Amber, Parker, Stella, Ryan, Steve, Terry) are also available when running in the Ambient Code Platform.
+
+## Directory Structure
+
+```
+spec-kit/
+├── .ambient/
+│   └── ambient.json           # Workflow configuration
+├── .specify/
+│   ├── scripts/               # Automation scripts
+│   │   └── bash/
+│   │       └── init-workspace.sh
+│   ├── templates/             # Document templates
+│   │   ├── spec-template.md
+│   │   ├── plan-template.md
+│   │   ├── tasks-template.md
+│   │   ├── ideate-template.md
+│   │   ├── checklist-template.md
+│   │   └── agent-file-template.md
+│   └── memory/                # Workflow knowledge base
+│       └── constitution.md
+├── .claude/
+│   ├── agents/                # Agent personas (20+ agents)
+│   └── commands/              # Slash commands
+│       ├── speckit.specify.md
+│       ├── speckit.analyze.md
+│       ├── speckit.clarify.md
+│       ├── speckit.plan.md
+│       ├── speckit.tasks.md
+│       ├── speckit.implement.md
+│       ├── speckit.checklist.md
+│       └── speckit.constitution.md
+├── CLAUDE.md                  # Agent usage guidelines
+└── README.md                  # This file
+```
+
+## Artifacts Generated
+
+All outputs are stored in `artifacts/specs/`:
+
+```
+artifacts/specs/
+└── [feature-name]/
+    ├── spec.md         # Feature specification
+    ├── plan.md         # Implementation plan
+    └── tasks.md        # Task breakdown
+```
+
+## Best Practices
+
+1. **Always initialize first:** Run `./.specify/scripts/bash/init-workspace.sh` before starting
+2. **Start with /specify:** Begin with a clear feature description
+3. **Iterate on clarity:** Use `/speckit.clarify` to refine underspecified areas
+4. **Sequential phases:** Follow specify → plan → tasks → implement for best results
+5. **Review before implementing:** Use `/speckit.analyze` to check consistency
+
+## Customization
+
+### Templates
+
+Customize templates in `.specify/templates/` to match your organization's standards:
+- `spec-template.md` - Feature specification format
+- `plan-template.md` - Implementation plan format
+- `tasks-template.md` - Task breakdown format
+
+### Constitution
+
+Update `.specify/memory/constitution.md` to encode your project's principles and constraints.
+
+### Agents
+
+Add or modify agents in `.claude/agents/` to match your team's roles and expertise.
+
+## Troubleshooting
+
+**Symlink errors during initialization:**
+- Ensure you run init script from the workflow directory
+- Check permissions on artifacts directory
+
+**Commands not found:**
+- Verify workflow is loaded in session
+- Check `.claude/commands/` directory exists
+
+**Templates not being used:**
+- Confirm templates exist in `.specify/templates/`
+- Check systemPrompt references correct template paths
+
+## Integration with ACP
+
+This workflow integrates with the Ambient Code Platform:
+- Load via workflow selection UI
+- Automatically clones into session workspace
+- Platform agents available alongside workflow agents
+- Artifacts stored in shared artifacts directory
+
+## Support
+
+- **Issues:** [github.com/ambient-code/workflows/issues](https://github.com/ambient-code/workflows/issues)
+- **Workflow Development Guide:** [WORKFLOW_DEVELOPMENT_GUIDE.md](../../WORKFLOW_DEVELOPMENT_GUIDE.md)
+- **Platform Documentation:** [ambient-code.github.io/platform](https://ambient-code.github.io/platform)
+
+---
+
+**Status:** Production Ready
+**Version:** 1.0
+**Maintained By:** Ambient Code Platform Team
diff --git a/workflows/template-workflow/README.md b/workflows/template-workflow/README.md
index c59b444..c0817ad 100644
--- a/workflows/template-workflow/README.md
+++ b/workflows/template-workflow/README.md
@@ -88,22 +88,24 @@ Each command file includes:
 
 ### Agent Personas: `.claude/agents/`
 
-Three example agents demonstrating different roles:
+The template includes three **example agents** demonstrating different roles. These are for illustration purposes only.
 
-1. **Alex - Solutions Architect**
-   - System architecture and design
-   - Technology decisions
-   - Technical leadership
+**For Production Use:**
 
-2. **Sam - Senior Software Engineer**
-   - Code implementation
-   - Testing and quality
-   - Technical execution
+1. **Platform Agents** - If your workflow runs in the Ambient Code Platform, agents from `platform/agents/` will be automatically loaded:
+   - **Amber** - Codebase intelligence, pair programming, proactive maintenance
+   - **Parker** (Product Manager) - Market strategy, customer feedback, business value
+   - **Ryan** (UX Researcher) - User insights, data analysis, evidence-based decisions
+   - **Stella** (Staff Engineer) - Technical leadership, implementation excellence, mentoring
+   - **Steve** (UX Designer) - Visual design, prototyping, user interface creation
+   - **Terry** (Technical Writer) - User-centered documentation, technical accuracy
 
-3. **Morgan - Product Manager**
-   - Requirements definition
-   - User stories
-   - Product strategy
+2. **Custom Agents** - Replace the example agents with your own workflow-specific personas as needed
+
+**Note:** Workflows are self-contained. If you want to use agents, either:
+- Rely on platform agents being loaded from context
+- Include your own agent definitions in `.claude/agents/`
+- Or both - custom agents can complement platform agents
 
 Each agent file includes:
 - Role and expertise
@@ -145,11 +147,11 @@ Each agent file includes:
    - Remove commands you don't need
    - Follow the structure in the examples
 
-4. **Adapt agent personas**
-   - Edit existing agents to match your team
-   - Add new agents for specialized roles
-   - Remove agents you don't need
-   - Update expertise and communication styles
+4. **Adapt agent personas (optional)**
+   - Platform agents (Amber, Parker, Stella, etc.) are automatically available
+   - Remove the example agents - they're just for illustration
+   - Add workflow-specific agents only if needed for unique expertise
+   - Platform agents handle most common roles
 
 5. **Test your workflow**
    - Load it in an ACP session
@@ -181,8 +183,9 @@ Start with just the essentials:
    - Start with the commands you actually need
    - Expand over time
 
-4. **Skip agents initially**
-   - Add agent personas later as needed
+4. **Skip custom agents initially**
+   - Platform agents (Amber, Stella, Parker, etc.) are already available
+   - Add workflow-specific agents only if truly needed
 
 ## Best Practices
 
@@ -204,11 +207,11 @@ Start with just the essentials:
 
 ### Agent Personas
 
-1. **Distinct roles**: Each agent has a unique perspective
-2. **Clear expertise**: Define what each agent knows
-3. **Communication style**: Give each agent a personality
-4. **When to invoke**: Explain when to use each agent
-5. **Realistic**: Base on actual team roles
+1. **Leverage platform agents**: Use Amber, Parker, Stella, Ryan, Steve, Terry from the platform
+2. **Add custom agents sparingly**: Only create workflow-specific agents for unique expertise
+3. **Clear expertise**: Define what each agent knows
+4. **Communication style**: Give each agent a personality
+5. **When to invoke**: Explain when to use each agent
 
 ### Directory Organization