AI-Enabled Development Playbook

How to Use This Playbook

This playbook is organized around “I want to…” use cases, not tool names. Find the phase that matches what you’re trying to do, and follow the numbered steps in order — each phase builds on the one before it.

This playbook covers ARMY-specific access, compliance, and deployment steps. For deeper agentic-development practice — BMAD workflows, training labs, prompt library — see Deloitte’s firm-wide Agentic Software Engineering Playbook.

⚠️ CRITICAL SECURITY NOTE: All steps below assume you are on a Deloitte-issued laptop, connected to the Deloitte VPN, and working within the ARMY Account’s approved tool provisioning. Do not attempt any step in this guide from a personal device or off-network.

Before You Begin

• Equipment: Deloitte laptop (Windows or Mac), connected to Deloitte VPN, for every step below.
• Timing: Budget ~2 hours end-to-end for Phases 1–3. Steps do not need to be completed in one sitting, but must be completed in order — each step depends on the previous one.
• Uniqueness: Every laptop is configured slightly differently. If a step is already complete on your machine, move to the next one. Screenshots referenced in team walkthroughs are illustrative, not exact matches.
• Access model: You will be provisioned either Codex or Claude Code (not both) for the Agentic Desktop, plus GitHub Copilot. Additional AI tool licenses are not granted outside your provisioned set.
• If you get stuck: Each phase below has its own troubleshooting table for tool-specific issues. For anything not covered there — or if you’re unsure which phase/team owns your blocker — reach out to the ADAG team at [ADAG contact — TBD].

⚠️ CRITICAL SECURITY NOTE: Output quality and accuracy from any AI tool is your responsibility. Review all AI-generated code and content before it leaves your local environment — nothing produced by these tools is final until it has passed human review, per GPS AI output-governance policy.

Phase 1: I want to set up my local development environment.Goal: Get your local machine and GitHub Enterprise access ready to run an AI-enabled development workflow.

Step 1 — Mac Users Only: Request Local Admin Privileges

Skip this step on Windows.

• Open Finder → Applications → double-click Privileges.
• Under Reason, select “For installing software” and click Request Privileges.
• Enter your Mac password when prompted, then click OK.
• Confirm success: a notification reading “Administrator privileges were successfully granted” appears top-right.
• Privileges expire after a period of time — if a later install fails, repeat this step before retrying.

Step 2 — Install VS Code

• Go to https://code.visualstudio.com/ in your browser (any browser is fine).
• Windows: Click Download for Windows.
• Mac: Click the “other platforms” link under the Windows download button, then select Mac.
• In the browser’s download bar, select Keep → Open File.
• Accept the license agreement, keep all default settings, and click Install.
• Once installed, check Launch Visual Studio Code and click Finish.
• If VS Code doesn’t auto-launch, search “VS Code” in your desktop search bar and open it.

Step 3 — Install Supporting Runtimes

These tools run in the background — you won’t interact with them directly, but AI tooling and the project repo depend on them.

• Windows — set Git Bash as your default VS Code terminal: In VS Code, press Ctrl+Shift+P → type “Terminal: Select Default Profile” → choose Git Bash. (No visible confirmation — this is expected.)
• Verify Git Bash: Close and reopen VS Code, open a terminal (Ctrl+`), and run:

  git version

  Success looks like 2.xx.x.windows.x.

Optional — BMAD-style tooling: If your team adopts BMAD-based agentic workflows (see Deloitte’s firm-wide Agentic Software Engineering Playbook), you’ll also want uv, a fast Python package manager: curl -LsSf https://astral.sh/uv/install.sh | sh (Mac/Linux) or powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows). Not required for the core setup in this playbook — Python above already covers general-purpose scripting needs.

Step 4 — Confirm Your Local IDE Environment

Your local IDE setup is on track once:

• VS Code opens without error.
• Node.js, Python, and (Windows only) Git Bash are installed.
• Your VS Code terminal defaults to Git Bash (Windows) or Terminal (Mac).

Step 5 — Request Access via the Ascend Engineering Foundation (AEF) Page

• Confirm you’re on the Deloitte VPN.
• Navigate to the Ascend Engineering Foundation (AEF) page → select GitHub Enterprise on the left-hand nav.
• Under Engineering Tool Stack → GitHub Enterprise, click Request Access.
  • If your screen already shows a green “Log in to GitHub” button, you’re already provisioned — skip to Step 6.
• Wait for an approval email from github@onecloud.deloitte.com (typically 1–2 hours) before continuing.

Step 6 — Retrieve Your GitHub Username

• Once approved, return to the AEF page.
• Next to “Log in to GitHub,” select Login Instructions.
• Copy your username from the pop-up — format: username_Deloitte.

Step 7 — Authenticate and Request Copilot Access

• Close the pop-up, click Log in to GitHub.
• Paste your username_Deloitte value — the form will drop the password field.
• Select “Sign in with your identity provider” → Continue.
• Return to the AEF page → select GitHub Copilot on the left-hand nav → click Request Access. (The separate “Copilot User Team” join flow no longer applies — this direct request is the only step needed.)
• Request Copilot access only after your GitHub Enterprise access (Step 5) is already granted — the two are provisioned sequentially, not in parallel.

⚠️ CRITICAL SECURITY NOTE: The GitHub Enterprise license request (Step 5) and the Copilot access request (Step 7) are two separate approvals. Holding one does not grant the other — both are required before you can use Copilot.

Troubleshooting — GitHub Enterprise

⚠️ CRITICAL SECURITY NOTE: Personal Access Tokens are credentials. Never commit a PAT to a repository, paste it into chat, or share it outside your own authentication flow. Store it only in your credential manager.

Phase 2: I want to enable and configure my AI coding assistant.Goal: Securely provision and configure your IDE-based AI companion, then connect it to your project repository.

Which Tool Do I Use?

You will be provisioned GitHub Copilot (everyone) plus either Codex or Claude Code — not both. Verify your provisioning before installing.

⚠️ CRITICAL SECURITY NOTE: Do not request a Claude Code license if you don’t already have one — none are currently being provisioned. Proceed with Codex + Copilot instead.

Step 1 — Confirm Your AI Tool Access

• Codex: Watch for an email inviting you to “Join workspace.” Click it, then confirm access by logging into ChatGPT with your Deloitte credentials — if the site is blocked, access has not yet propagated.
• Claude Code: Watch for an email from Anthropic (subject: “[EXT] You’re invited to join Deloitte on Claude” — check junk mail). Confirm by signing in at claude.ai/new and checking the left-hand pane for a Code option.
• GitHub Copilot: Confirmed once your Phase 1, Step 7 access request is approved.

Step 2 — Install Your AI Assistant Extension(s) in VS Code

For each tool you’re provisioned:

1. Open VS Code → Extensions tab (left-hand icon, looks like stacked blocks).
2. Search the exact extension name and click Install:
   • Codex (select Release Version if prompted)
   • GitHub Copilot Chat
   • Claude Code for VS Code (only if pre-provisioned)

Codex authentication:

• Click Sign in with ChatGPT (opens your browser).
• Enter your Deloitte email → if prompted for a login method, select DeloitteUS → Continue.
• Confirm the “Signed into Codex” page, close it, return to VS Code (auto-authenticated).
• Click through the 4 onboarding screens (Windows only — Mac skips this).
• When prompted “Set up Agent sandbox to continue,” select Set up, authenticate with Deloitte credentials, and choose “Deloitte Internal Support” as the reason. If admin sandbox setup fails, select backup sandbox — this is expected behavior, not an error.

GitHub Copilot authentication:

• Click Chat (top-right of VS Code).
• Type a test prompt (e.g., “Can you verify what instance of GitHub Copilot you’re running on?”). A valid response confirms installation.

Claude Code authentication (pre-provisioned users only):

• Select Trust Publisher & Install when prompted.
• Click Claude.ai Subscription → Open on the external website pop-up → Authorize.
• Confirm the “Build something great” message, close the browser, and return to VS Code — Claude Code is now available in the right-hand pane.

Step 3 — Clone the ARMY Project Repository

• In VS Code: File → New Window → Source Control → Clone Repository.
• Paste your team’s designated GPS Agentic Desktop repository URL and press Enter.
• Select or create a destination folder, then Select as Repository Destination.
• Confirm Open and “Yes, I trust the authors” (do not check the “parent folders” box).
• Open a new terminal (Terminal → New Terminal) and run the management script for your OS:
  • Windows (PowerShell): .\scripts\manage.ps1
  • Mac/Linux: ./scripts/manage.sh
• When prompted, enter the numbers corresponding to the AI tools installed in your IDE. Completion is signaled by a “Done” message.

Step 4 — Run Guided Setup Agents

In your AI tool’s chat pane, run and answer all prompted questions for:

• gps-user-setup — captures your individual working preferences.
• gps-project-setup — captures project-specific configuration.

Once complete, ask your AI tool to write the responses to README files so future agent sessions can reference them.

Troubleshooting — AI Assistant Setup

If none of the above resolves your issue: (1) ask your AI tool to help debug the exact error text, (2) post in your team’s Agentic Workspace channel with a screenshot and the step number, (3) escalate to your ARMY Account engineering POC.

Phase 3: I want to follow development guidelines and prompting best practices for working with AI.Goal: Use your AI coding assistant effectively and safely — planning before building, writing prompts that get useful results, and reviewing everything before it ships.

Note on sourcing: Unlike Phases 1, 2, and 4, this phase is not drawn from a verified ARMY Account or Deloitte-internal reference guide — it’s generic, tool-agnostic guidance reflecting common practice across Codex, Claude Code, and Copilot. Treat it as a starting point, and defer to any team- or account-specific standard your lead provides.

Step 1 — Plan Before You Build

For any task touching more than one file, or where the requirements aren’t fully pinned down, use your tool’s planning mode before it starts writing code:

• Claude Code: Use /plan mode (or ask it to “make a plan before making changes”) to have it explore the codebase and propose an approach before editing anything.
• Codex: Ask it to outline its approach first, in Chat or Agent mode, before switching to Agent (Full Access) to execute.
• GitHub Copilot Chat: Use Ask mode to talk through the approach before switching to Edit/Agent mode to make changes.

Planning first surfaces bad assumptions — about which files are involved, what the existing pattern is, what “done” means — while they’re still cheap to fix.

Step 2 — Write Effective Prompts

• State the goal and constraints together (e.g., “add input validation to this form, without changing the existing submit handler’s signature”).
• Reference exact files, functions, or symbols rather than describing them generically — this cuts down on the tool guessing at the wrong target.
• Break large asks into smaller turns. A prompt that tries to do five things at once is harder to review than five prompts that each do one.
• Point the tool at existing conventions in the repo (naming, error handling, test structure) instead of letting it invent new ones.

Step 3 — Review Every AI-Generated Change

• Review AI-generated code the same way you’d review a teammate’s pull request — read every line before accepting it, don’t just skim the diff summary.
• Watch specifically for hardcoded secrets/credentials, injection risks, and authentication/authorization logic — these are the categories most likely to look plausible but be wrong.
• Ask the tool to explain its reasoning or run the test suite before you accept a change you’re unsure about.
• Nothing is final until it has passed human review — per GPS AI output-governance policy, this applies to every AI-assisted change, not just ones bound for production (see Phase 4).

Step 4 — Know Where to Go Deeper

• For BMAD-style agentic workflows, a shared prompt library, and hands-on training labs, see Deloitte’s firm-wide Agentic Software Engineering Playbook.
• If you hit a question this phase doesn’t answer: ask your AI tool first, then post in your team’s Agentic Workspace channel, then escalate to your ARMY Account engineering POC if still unresolved.

Phase 3 Completion Checklist

• You default to a planning step (/plan or equivalent) before multi-file or ambiguous tasks.
• Your prompts reference specific files/functions and existing conventions, not generic descriptions.
• Every AI-generated change is reviewed like a PR before you accept it.
• You know your escalation path: AI tool → Agentic Workspace channel → ARMY Account engineering POC.

Phase 4: I want to publish my application to production.Goal: Move an application from local AI-assisted prototype to a fully governed, compliant, deployed state under Deloitte’s ARMY Account cloud and security controls.

⚠️ CRITICAL SECURITY NOTE: This phase is a governance gate, not a suggestion. Nothing built in Phase 1–3 may be deployed, exposed to a client, or connected to production data until it has cleared APM registration, PAM-governed access provisioning, and OneCloud subscription review. AI-assisted code carries the same compliance obligations as any other code.

🔧 Advanced phase — set expectations accordingly: Unlike Phases 1–3, this phase routes through multiple external teams and approval systems (APM approvers, PAM/AD teams, Cloud Engineering, pipeline reviewers). This playbook explains what each step does and who to go to — it is not a substitute for expertise in APM, PAM, or OneCloud administration, and you shouldn’t expect to complete every step solo in one sitting. Steps below are marked 🔧 Advanced where hands-on coordination with another team is the norm, not the exception.

⏱️ Time expectation: Budget days to weeks, not hours — APM approval routing, MAC entitlement approval, and Secret Server provisioning each depend on another person or team acting, not just your own effort.

Note on sourcing: Phases 1–2 above and Steps 1–3 below (APM, MAC/Secret Server, and OneCloud) are drawn directly from verified Deloitte reference guides (Agentic Desktop pilot setup guide, MAC User Guide, Secret Server User Guide and FAQs, ServiceNow KB0041744 — APM: How to Register a Product in APM, and Request & Relate Application Service(s), and the OneCloud Console User Guide). The OneCloud guide is explicitly written for non-US member firms — if your screens don’t match Step 3 below, contact US Hosting Services or your ARMY Account Cloud Engineering POC to confirm US-specific navigation before proceeding. Step 4 below (deployment pipelines) leads with generic, publicly-documented GitHub Actions practices — pending an ARMY Account-specific CI/CD standard, treat it as a starting template rather than settled policy. Phase 3 (development guidelines and prompting best practices) is generic guidance, not drawn from an ARMY-specific verified reference — see the sourcing note at the top of that phase.

Step 1 — Register the Application as a Product in APM 🔧 Advanced

Source: ServiceNow KB0041744 — “APM: How to Register a Product in APM, and Request & Relate Application Service(s).”

• Confirm the application does not already exist as a registered Product in APM (search by name/team/account before creating a new record — duplicate Product records fragment ownership and complicate audits).

Navigation

• Open the Service Portal (https://deloitteus.service-now.com/sp), search APM, and select Register a Product in APM.
• The first question, Enter the Product Portfolio, determines where the record is actually created:
  • Consulting or Advisory (FKA Risk Financial Advisory) portfolios → custom-developed or internal-use assets go to Master Asset Inventory (MAI) on Deloitte Asset Portal first, not directly into APM. MAI assets sync into APM automatically once approved there.
  • All other portfolios → proceed directly in the APM form below.

Complete the form (sections appear conditionally based on your earlier answers — select the ? icon next to any question for inline help):

• Click Submit. Approval routing: 1 approval (Application Portfolio Manager) if Managing Organization is EA or FSS; 2 approvals (Application Portfolio Manager + Financial Portfolio Manager/TBM) otherwise. See KB “APM - How to Approve or Reject a Product Request” for the approver-side steps.
• Attach the application’s architecture/data-flow summary if not already captured above — required for security and compliance review.
• Obtain Product approval/sign-off before requesting any downstream access (PAM) or cloud resources (OneCloud).

⚠️ CRITICAL SECURITY NOTE: Do not proceed to PAM or OneCloud provisioning on an unregistered or unapproved APM Product. Downstream teams will reject access/subscription requests that don’t trace to an approved Product ID.

Escalation: SolveIT first; if unresolved, US Contact Center at 1-800-335-6488 (1-800-DELOITTE).

Step 2 — Provision Access via Privileged Access Management (PAM) 🔧 Advanced

Deloitte’s PAM flow is two sequential systems, not one. You must complete them in order: MAC grants you the entitlement; Secret Server is where you actually retrieve the credential to use it.

Stage A — Request the entitlement in MAC

• Identify the specific privileged AD group/role/service account your deployment pipeline requires (e.g., deployment service principal, database admin, secrets access) — request the minimum necessary entitlement, not broad admin access.
• In MAC, go to Manage Access → Select Users (choose yourself or, if requesting on behalf of a report, add them first under Add Direct Report).
• Under Manage Access, search for the required entitlement/AD group by name. For AD-based access, confirm the correct group by its domain suffix (shown as Group[Domain]).
• Select the entitlement, proceed to Review and Submit, and add a comment describing the business justification — approvers see this comment.
• If prompted, confirm/update your Primary Access Approver (typically your manager, engagement lead, or project executive) — this person must approve the request.
• Track progress under My Work → Access Requests → Details. You’ll receive an email once the approver processes the request.
• Tie the justification for this request to your approved APM Product ID from Step 1.

⚠️ CRITICAL SECURITY NOTE: Do not request standing/broad AD group membership as a workaround for a narrower entitlement that doesn’t exist yet — submit a ServiceNow ticket to the AD Team (via your Product/entitlement owner) to have the correct scoped entitlement created instead.

Stage B — Check out the credential in Secret Server

Once MAC access is approved, the privileged account appears in Secret Server. To actually use it:

• Log into Secret Server from the Deloitte VPN or office network (the uspcs hostname only resolves on Deloitte’s internal network — it is not reachable from the open internet) using your Deloitte Outlook username (no @deloitte.com suffix) + password + MFA code from Azure Authenticator, and select the correct Domain.
• Locate the secret/account and click Check Out Secret — you’ll be required to enter a “Reason for View” comment; this is logged for audit.
• Retrieve the credential: either click the account’s built-in RDP/PuTTY Launcher (enter the target computer name), or manually copy the username/password (Unlock → Copy to Clipboard) and paste them into a manually-opened Remote Desktop Connection.
• When finished, sign out of the remote session correctly using Start → Sign Out — closing the RDP window with the X button does not sign you out and can trigger an account lockout.
• Click Check In on the secret in Secret Server as soon as you’re done. Checked-out passwords remain valid for 24 hours; if not checked in, the system auto-checks it in and the password is left unchanged unless 30 days pass with no checkout, which forces a rotation.

⚠️ CRITICAL SECURITY NOTE: Never embed MAC-granted or Secret Server-issued credentials, tokens, or secrets in source code, commit history, or AI chat prompts. Reference them exclusively via your pipeline’s approved secrets manager — Secret Server is for interactive checkout, not pipeline-time secret injection.

Step 3 — Provision a OneCloud Environment/Project (Check for Existing First) 🔧 Advanced

Source: OneCloud Console User Guide — general/non-US representation. Confirm with US Hosting Services or your Cloud Engineering POC if your tenant’s screens differ.

• Before requesting a new project: search the OneCloud Console for existing projects tied to (a) your APM Product ID, (b) your account/engagement code, and (c) your team name. Existing projects are the default reuse path.
• If an existing project is found: request access/role assignment on it rather than provisioning a new one.
• If no existing project is found, provision a new one as follows.

Navigate: OneCloud Console → My OneCloud (left nav) → click + Add New in the My Projects tile. This opens the Create OneCloud Service guided form (5 sections).

⚠️ CRITICAL SECURITY NOTE — APM dependency: The App/APM ID field in the Tags section is the Product ID from Phase 4, Step 1. Complete the APM registration before starting this form — the Tags section includes a “Register my application in Service Now” link if you haven’t, but going back mid-form to register costs you a restart.

• Tag all new resources with the correct cost center, APM Product ID, and data classification at creation time — untagged resources are a common audit finding.

Adding an environment to an existing project: My OneCloud → select the project in My Projects → in the Environment tile, click + Add New (only visible if an environment type is still available to add) → follow the same Section III steps above → Submit.

⚠️ CRITICAL SECURITY NOTE: Duplicate OneCloud projects are one of the most common sources of untracked cloud spend and shadow infrastructure. The search-before-create step above is mandatory, not optional — treat it as a hard gate before any new project request is submitted.

• If the application needs a custom domain (e.g., a subdomain of armyaccount.deloitte.com), submit a DNS/domain registration request once your OneCloud environment is provisioned, so you have a target hostname to point the record at.

Step 4 — Configure Secure Deployment Pipelines 🔧 Advanced

Note on sourcing: No ARMY Account-specific CI/CD standard or GitHub Actions runbook has been supplied for this section. The guidance below leads with GitHub Actions (since Phase 1 already provisions GitHub Enterprise for this account) using generic, publicly-documented GitHub Actions security practices — it is not yet verified against an ARMY Account or Deloitte-internal pipeline policy. Treat specifics (job structure, required checks, naming) as a starting template to confirm with your ARMY Account Cloud Engineering POC, not as settled policy. Other CI/CD tooling may be approved for this account — where it is, substitute the equivalent control at each bullet below rather than treating GitHub Actions as mandatory.

If using GitHub Actions (primary path, given GitHub Enterprise is already provisioned in Phase 1):

• Structure the workflow as separate jobs — e.g., build → scan → deploy — so a failed scan blocks deployment rather than running in parallel with it.
• Authenticate to cloud/OneCloud resources using OpenID Connect (OIDC) federated credentials configured on the deploy job, not long-lived cloud access keys stored as repo secrets.
• Store any secret the pipeline does need (API keys, service credentials tied to your PAM-provisioned access) in GitHub Environment secrets, scoped to the specific environment (e.g., production), never in repo-level secrets, workflow YAML, or committed .env files.
• Configure the production GitHub Environment with required reviewers — this is the mechanism that enforces the human sign-off gate below as a hard stop in the pipeline, not just a policy statement.
• Add required status checks in branch protection rules so the scan job (dependency/vulnerability scanning, e.g., CodeQL or an equivalent SCA tool) must pass before a PR can merge to the deploy-triggering branch.
• Restrict which branches/tags can trigger the deploy job (e.g., on: push: branches: [main] plus environment protection), so no feature branch or fork can deploy directly.

Regardless of pipeline tooling:

• Deploy only through the account’s approved CI/CD pipeline — no manual/ad hoc pushes to production infrastructure.
• Ensure pipeline credentials are sourced from the secrets manager tied to your PAM-provisioned access, never hardcoded.
• Confirm the pipeline includes required security gates (dependency/vulnerability scanning, code review sign-off, and any AI-generated-code review step) before promotion to production.
• Route all production promotions through the review/approval stage — human sign-off is required before external-facing release, consistent with GPS AI output-governance policy.

Phase 4 Completion Checklist

• APM Product registered and approved.
• PAM access provisioned at minimum necessary privilege.
• OneCloud subscription confirmed reused (preferred) or newly justified and tagged.
• Custom domain (if needed) requested via the DNS registration form and DNS record confirmed.
• Deployment pipeline passes all required security gates.
• Human review completed prior to production release.

Appendix: Tool Glossary