Customizing TFS Process Guidance

Team Foundation Server (TFS) is the core of Visual Studio Team System (VSTS), an Application Lifecycle Management (ALM) platform from Microsoft. TFS offers integrated team portal, version control, work-item tracking, build management, process guidance and business intelligence functionality. TFS provides interactive online documentation based on Microsoft Solutions Framework (MSF), a proven methodology for planning, designing, implementing and deploying information systems and solutions.

MSF for Agile Software Development

Out of the box, TFS 2008 comes with two varieties of process guidance: MSF for Agile Software Development and MSF for CMMI Process Improvement. MSF Agile process was designed for smaller teams and teams that use agile development practices, while MSF CMMI process was designed for larger organizations, particularly those using CMMI (Capability Maturity Model Integration) approach, teams that require a higher degree of control and visibility over their projects.

You can learn more about MSF Agile and MSF CMMI by reading the process guidance that comes with TFS. If you don’t have access to a TFS project with the process flavor you are interested in, you can download it from MSDN using the links below. Simply open ProcessGuidance.html located in the Windows SharePoint Services\Process Guidance folder in the location where you extracted the project template files.

MSF Process Guidance is Only a Template

While MSF Agile and MSF CMMI templates can serve as good starting points for many organizations, there is rarely a perfect fit. The Agile template fits well most of the small- to mid-size IT organizations, however it uses terminology that is too specific to agile software development. Its term Scenario represents what is commonly referred as Service Request or Change Request; the term Bug refers to what is commonly known as Trouble Ticket or Defect Report. The CMMI template uses more appropriate terminology, but due to the large number of work-item types and roles, it is simply an overkill for most organizations.

Today, a typical MIS department usually has a small number of roles (such as Business Analyst, Project Manager, Developer, Database Administrator, Help Desk Technician) established and follows an existing process for managing the change requests and trouble tickets. This process may be based on paper or electronic forms, it may not be perfect, but it is already working. When this organization adopts TFS to improve their process, should they go ahead and adopt MSF Agile or MSF CMMI?

Adopting a new process approach (what you do) at the same time as adopting a new process management tool (how you do it) is a risky proposition. People are creatures of habit and require time to change either the process they follow or the tools they use. Imagine if all cars in a country had to be changed to use voice control instead of traditional steering (change what you do) and that people had to speak to their cars in Esperanto (change how you do it). In the resulting chaos, we can be certain that both the congressman who proposed this improvement and the president who didn’t veto the proposal will not be as popular anymore.

When adopting TFS, unless your IT organization is following the MSF Agile  or the MSF CMMI process to the letter, it is much safer to start by customizing the TFS process to match your own. Once your organization is comfortable using TFS as the new process management tool, you can begin adjusting the process itself using TFS. Microsoft provided extensive documentation (see links below) on how to customize the workflows, work items, reports and other features of TFS. However, customization of the process guidance received relatively little attention. Yet in the process of adopting TFS, providing matching guidance for a customized process is very important to ensure the overall success. Outdated guidance will cause confusion, mistakes, delays and frustration for the MIS department and its business partners. So how do we change it?

VSTS Process Guidance Generator

Microsoft used the Guidance Generator to produce MSF Agile and MSF CMMI guidance for TFS 2008. This tool replaced MSFWinBuild which was used to produce the guidance in TFS 2005. Unlike its predecessor, it uses plain XML file to define contents of the guidance and T4 templates to generate the actual collection of HTML files, included in TFS project templates as process guidance. The remainder of this article will show a typical set of steps you would need to perform to customize guidance for your TFS project.

Installing Guidance Generator
  • Guidance Generator Archive PropertiesDownload latest version of the Guidance Generator ( at the time of this writing) to your local hard drive.
  • Unblock the ZIP archive you downloaded as shown on the right. This will ensure that the application will not run into any unexpected security errors.
  • Extract files from the unblocked archive to your hard drive.

If you are running a 64-bit version of windows, you will need to use the CorFlags command line tool to make sure that the generator runs in 32-bit mode. This will help you to avoid errors that occur when the generator attempts to load 32-bit-only assemblies it requires.

  • Use Command Prompt window to execute the following command in the bin\bin sub-folder at the location you extracted the files.
C:\GuidanceGenerator\bin\bin>corflags TextTemplatingMultiprocessor.exe /32BIT+
Microsoft (R) .NET Framework CorFlags Conversion Tool.  Version  3.5.21022.8
Copyright (c) Microsoft Corporation.  All rights reserved.


Guidance Generator, Extracted FilesBuilding Process Guidance

Once you have the Guidance Generator installed, your first task is to pick a template (Agile or CMMI) that you will be using as a starting point in your customization. If you are customizing guidance for an existing TFS project, you will want to minimize the amount of editing, so pick the template that matches matches your project.

  • Double-click the Run Tool.cmd file in root folder at the location you extracted the files to start the generator.   
  • In the TemplateProcessor window, enter the following parameter values.

    Source DSL File:      agile-guidance.guidance

    Template Directory: HTML_Templates

    Target Directory:       agile-Generated\Process Guidance\Supporting Files

The source file provides content of the guidance. In this example, we are generating process guidance from the source file called agile-guidance.guidance to the output directory called agile-Generated. To generate CMMI guidance, we would need to change these values to cmmi-guidance.guidance and cmmi-Generated respectively.

Guidance Generator, Application

  • Click the Go button.

The generator runs for a while and you should see the a log displayed in its output window with information about the number of files that were generated. Once you see “Done”, you can open the generated guidance by double-clicking the ProcessGuidance.html located in the agile-Generated\Process Guidance folder. The actual output files are generated in the agile-Generated\Process Guidance\Supporting Files folder.

Generated Guidance Files

Customizing Guidance Content

The guidance content is located in the .guidance files - agile-guidance.guidance and cmmi-guidance.guidance. These are rather large XML files that define topics describing team member roles, work streams, activities, work products, work items, reports, glossary entries and more.

Agile Guidance Source File

Limited information about the structure of this file can be found in the UserGuide - Guidance Generator.pdf located in the root folder where you extracted the Guidance Generator files downloaded from CodePlex. This information is by no means complete nor, due to its volume, would not be practical to describe in a single article. In one sentence, this structure can be summarized as this. There is a one-to-one relationship between the major xml elements and the generated HTML files, for example, BusinessAnalyst.htm file is generated from the XML element <Role Key=”BusinessAnalyst”>. If you want to change content for particular HTML file, find the XML element with matching Key and change its contents.

Source XML

Business Analyst, XML Definition

Generated Output

Business Analyst, Generated HTML

Editing such a large and complex XML file is challenging. It was not meant to be edited by hand and the internal tool Microsoft created for editing it was not released to public. You may be tempted to use the XML schema file, GuidanceModelSchema.xsd, to enable IntelliSense and enhance your editing experience in Visual Studio, but unfortunately, it appears to be outdated and doesn’t match the supplied .guidance files.

Instead, you will need to frequently re-run the generator to verify that content you are modifying produces the HTML you expect. You can reduce the amount of time it takes to regenerate output by setting Template Files parameter to regenerate only a the particular type of file you are working on. For example, Business Analyst.htm is generated by the T4 template called Role.htm and you can regenerate only role files like so.

Generate Only Specific Files

Customizing Guidance Output

Guidance Generator uses T4 templates located in the HTML_Templates directory to generate output HTML files (in the Supporting Files directory). There is one template file for each major type of XML element in the .guidance file (<Role>/Role.htm, <Activity>/Activity.htm). As you can see, the T4 template files are saved with .htm extension which might be confusing at first.

Guidance Generator Templates

The final HTML files rely on additional web resources - JavaScript, Cascading Style Sheet and image files located, respectively, in the Code, CSS and Images sub-folders of the Supporting Files folder where the generated output files are saved. Each guidance (Agile and CMMI) has its own set of supporting files.

To change look and feel of the generated HTML, you can start by changing the CSS\msf.css style-sheet or changing the image files to display your company’s logo. However, if you need more substantial changes, you may have to modify the T4 templates that generate the HTML. For detailed information about T4, please see my previous article, Text Template Transformation Toolkit.

Publishing New Guidance

Once you finish changing the guidance, you can package it in a TFS process template, or simply upload it to the Process Guidance folder on your team portal.


TFS is a powerful collaboration platform for IT organizations. Although TFS comes with two pre-packaged process templates (MSF Agile and MSF CMMI), it is often beneficial to customize them to better fit the process already used by your organization. It is also important to keep documentation in sync with the process you are using and minimize confusion among the members of the immediate IT team as well as the business users. Guidance Generator is a powerful tool for customizing the built-in process guidance that comes with TFS. Although the Guidance Generator is not very easy to use, the interactive documentation system it produces is well designed, easy to use and would be challenging to replicate in hand-crafted HTML or Word files. In most cases you will want to start with an existing process guidance that most closely matches your current process and customizing it, hopefully by simply removing the MSF concepts you currently don’t use.


Write a Comment

Take a moment to comment and tell us what you think. Some basic HTML is allowed for formatting.

Reader Comments

Thank you Oleg for this very complete post on TFS process guidance. This article should be for those who think TFS is just another versioning control system.

[…] Oleg Sych talks about the customization of the TFS Process Guidance with T4. […]

Hey Oleg, what directory should I download this tool to? Or doesn’t it matter?

I don’t think it matters very much. I had it close to the root of C: drive when I wrote this article.

Do you know if there are any plans to upgrade this project to support the Process shipping in VS2010?

Hi Oleg,

I was wondering if you know how to change the in the .guidance?

I’m trying to customize the Process Guidance and with the changes made I’d like to ensure that users aren’t confused to assume that it is the process guidance provided out of the box by Microsoft.

I tried to change the title and re-run the tool, but it didn’t actually change the title.

Thanks for the very detailed explanation. My 64bit environment had me stumped for a while…corflags to solve the problem!

Oleg, Could you (in addition to general T4 guidance) provide some information for customising the MSF templates. Information about this is not readily available. I have a problem with the GuidanceModelDirectiveProcessor (custom processor) inheriting from ModelingTextTransformation and Visual Studio complaining that “The type ‘Microsoft.TeamFoundation.GuidanceModel.GuidanceModelDirectiveProcessor’ of the directive processor named ‘GuidanceModelDirectiveProcessor’ does not derive from Microsoft.VisualStudio.TextTemplating.DirectiveProcessor”. I don’t seem to find much information explaining this. Thanks for your help.


This error may be caused by two different versions of Microsoft.VisualStudio.TextTemplating.dll loaded by the template engine host. I haven’t encountered this problem with the TextTemplatingMultiprocessor.exe specifically, but have seen a similar error in Visual Studio 2010 with code compiled against the older version of the Visual Studio SDK.

Unfortunately, I can’t offer any more insight than this. Perhaps you could use fuslogvw.exe from the .NET SDK to see which assemblies are being loaded and where there problem might be.


Hi Oleg,

I’m trying to create a new type in the agile-guidance to extend the reports section (Report type currently exists, and I want to add CustomReport type).

When I try to do this though and make reference to this new type in an HTML Template page I get the following error

“Compiling transformation: The type or namespace name ‘CustomReport’ could not be found (are you missing a using directive or an assembly reference?)”

I am supposed to update the guidanceModelSchema.xsd? I tried in a couple of places but I still continued to get the error message.

Thanks, really your post was my first step to start customizing the process, I already create a video on how to do a full complex customization here: