Reference: AI Workflow Tools

Quick reference material for the GSD workflow, CLAUDE.md system context, memory systems, and plan mode decision framework used in Module 6.

1. GSD Command Quick Reference

Command	When to Use	What It Does
`/gsd:new-project`	Starting a new scoped AI task	Creates `.planning/PROJECT.md` with project scope, deliverables, constraints
`/gsd:discuss-phase N`	Before planning phase N	Locks requirements into `CONTEXT.md` via structured Q&A; this context is what planners and executors see
`/gsd:plan-phase N`	After discuss, before execute	Runs research + task decomposition; generates `PLAN.md` with tasks, done criteria, file targets
`/gsd:execute-phase N`	After plan is reviewed	Executes tasks atomically; each task commits to git with its own message and acceptance criteria
`/gsd:verify-work`	After execute completes	Validates outputs against plan acceptance criteria; reports deviations

Typical flow:

/gsd:new-project
  → describe project scope, deliverables, constraints

/gsd:discuss-phase 1
  → answer questions about requirements
  → result: .planning/CONTEXT.md with locked decisions

/gsd:plan-phase 1
  → review generated PLAN.md
  → modify if needed before executing

/gsd:execute-phase 1
  → watch atomic commits as tasks complete
  → review each task's output

/gsd:verify-work
  → review verification report

2. CLAUDE.md Template

Use this template for any DevOps project directory. Customize the sections to match your environment.

# [Project Name] — [Purpose]

## System State
- Cluster: [cluster context name, e.g., kind-lab]
- Services: [service-name (port), service-name (port)]
- Namespaces: [app namespace], [infrastructure namespace]
- Tool access: [key tools and their endpoints, e.g., Prometheus: NodePort 30091]

## Tool Versions
- Kubernetes: [version]
- Helm: [version]
- Key operators: [operator name and version]

## Constraints
- [Constraint 1: what NOT to do]
- [Constraint 2: resource or cost limitation]
- [Constraint 3: scope boundary]

## Vocabulary
- "[internal term]" = [what it means in this project context]
- "[service name]" = [what it does and how it's identified]

## Context Engineering Notes
- 4-layer context model applies: Task / Role / System / Procedure
- For IaC generation: always specify Kubernetes API versions in System context
- For YAML output: include exact label conventions in Procedure context

Module 6 Lab Example

The monitoring stack CLAUDE.md from Section 2 of the lab:

# Monitoring Stack for Reference App

## System State
- KIND cluster: context "kind-lab"
- Services: api-gateway (8080), catalog (8081), worker (8082)
- Namespace: app (reference app), monitoring (Prometheus + Grafana)
- Prometheus: NodePort 30091, Grafana: NodePort 30090

## Constraints
- No paid services — all resources local or free-tier
- Kubernetes 1.32, Helm 3.18, Prometheus Operator CRD v1
- Do not modify reference-app/ source code

## Vocabulary
- "alerting rules" = PrometheusRule CRD in monitoring namespace
- "dashboard" = Grafana JSON provisioning file in configmap

3. claude-mem Commands

claude-mem provides cross-session memory for Claude Code sessions.

Command	What It Does
`/mem search [query]`	Semantic search across previous Claude Code sessions — returns relevant context fragments
`/mem timeline`	Shows recent Claude Code session history with timestamps
`/mem recent`	Surfaces the most recent decisions and patterns

Usage pattern at session start:

/mem search [topic relevant to today's work]

Example: Before working on Helm charts today, run /mem search helm serviceMonitor to surface any decisions about ServiceMonitor configuration from previous sessions.

4. Crush MCP Memory Configuration

Add to your Crush MCP configuration file (typically ~/.config/crush/config.json or mcp.json):

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Once configured, Crush can explicitly save and retrieve facts across sessions using the MCP memory protocol.

Save a fact:

Remember: ServiceMonitor for kube-prometheus-stack requires the label
release: prometheus to be discovered by the Prometheus operator.

Retrieve facts:

What do I know about Prometheus ServiceMonitor label requirements?

5. Plan Mode Comparison

Feature	Quick Plan (`/plan`)	GSD plan-phase
Where	Claude Code built-in	GSD slash command
Scope	Single task or request	Multi-task phase with research
Output	Conversational description	Structured `PLAN.md` file (version-controlled)
Research	No	Yes — GSD researches APIs, schemas, dependencies
Traceability	None — lives in chat history	Full — PLAN.md committed to git
Review process	Immediate approval/modify	Review file before executing
Best for	Single-file, low-risk changes	Multi-file, production-impact, needs audit trail
Overhead	Low	Higher (appropriate for the risk)

Decision rule: If a junior engineer's change would require a design review before merging, use GSD plan-phase. If it would just need a quick PR review, use /plan or direct execution.

6. Context Engineering Checklist

Before starting any AI-assisted infrastructure task, verify your context is in place:

Session context

CLAUDE.md present? Does the current directory have a CLAUDE.md with system state and constraints?
Right context injected? Are you using @file references for the specific files AI needs (not @ for the entire repo)?
Token budget reasonable? Check /cost after a few interactions — if context is growing fast, consider selective injection

4-Layer context model

Task (Layer 1): Is the output clearly specified? File names, Kubernetes kinds, exact deliverable?
Role (Layer 2): Does AI have an expertise frame? "SRE on production K8s platform" vs generic "developer"?
System (Layer 3): Does AI know your environment? Kubernetes version, operators, namespaces, service names, ports?
Procedure (Layer 4): Does AI have constraints? Label requirements, naming conventions, API version restrictions?

If System (Layer 3) or Procedure (Layer 4) is missing, the output will be generic. Generic output in production infrastructure is a risk, not an asset.

For GSD workflow specifically

Project scope documented? .planning/PROJECT.md exists and reflects current scope
Requirements locked? CONTEXT.md has been generated via discuss-phase — not just implied
Plan reviewed? PLAN.md has been read and approved before execute-phase runs
Outputs verified? verify-work run after execution and results reviewed

7. Session Handoff Checklist

Before ending a Claude Code or Crush session on an in-progress infrastructure task:

Decisions logged: Any architectural decisions, constraints discovered, or trade-offs made are documented (in CLAUDE.md, CONTEXT.md, or a commit message)
State captured: Current progress is committed to git — no uncommitted work
Context preserved: If using GSD, STATE.md reflects current position (phase, plan, blockers)
Memory updated: Any patterns or decisions worth preserving across sessions are saved (claude-mem or MCP memory)
Next action noted: The first thing to do in the next session is written down — prevents re-establishing context unnecessarily

A 2-minute session handoff prevents a 15-minute context re-establishment at the start of the next session.

Back to lab: Lab: AI Workflow Tools

1. GSD Command Quick Reference​

2. CLAUDE.md Template​

Module 6 Lab Example​

3. claude-mem Commands​

4. Crush MCP Memory Configuration​

5. Plan Mode Comparison​

6. Context Engineering Checklist​

Session context​

4-Layer context model​

For GSD workflow specifically​

7. Session Handoff Checklist​