Claude Code Workflow Template

A structured template for building applications with Claude Code using the PIV Loop workflow — Prime → Implement → Validate.

Clone this repo as the starting point for any new project. It provides slash commands, reference documentation, skills, and best practices for AI-assisted development.

myworkshop branch — personalised for Charles Vosloo / CogStack. Wired into ~/.claude/ via symlinks so commands are available globally across all projects.

Global Installation (CogStack Setup)

This branch is designed to be cloned once and symlinked into ~/.claude/ so all commands, rules, and reference docs are available in every Claude Code session — not just per-project.

# 1. Clone to your home directory
git clone -b myworkshop https://github.com/journeyman33/claude-code-template ~/claude-code-template
cd ~/claude-code-template

# 2. Symlink into ~/.claude/ (preserves settings.json, sessions, history)
mkdir -p ~/.claude
ln -sfn ~/claude-code-template/.claude/commands  ~/.claude/commands
ln -sfn ~/claude-code-template/.claude/rules     ~/.claude/rules
ln -sfn ~/claude-code-template/.claude/reference ~/.claude/reference
ln -sfn ~/claude-code-template/.claude/skills    ~/.claude/skills

# 3. Populate CLAUDE.md with your project/machine context (see below)
# Then symlink it into any working directory you run claude from:
ln -sfn ~/claude-code-template/CLAUDE.md ~/.hermes/CLAUDE.md  # example

# 4. Verify symlinks
ls -la ~/.claude/ | grep '\->'

Note: ~/.claude/ holds Claude Code's runtime state (sessions, history, MCP cache, settings). Only the four subdirectories above are symlinked — everything else stays native.

What's Included

.agents/
└── plans/              # Feature implementation plans (generated by /plan-feature)

.claude/
├── commands/
│   ├── prime.md              # Load codebase context into Claude
│   ├── plan-feature.md       # Create a detailed implementation plan
│   ├── execute.md            # Execute a plan step-by-step
│   ├── commit.md             # Atomic commit helper
│   ├── create-prd.md         # Generate a PRD from conversation
│   ├── create-rules.md       # Auto-generate CLAUDE.md from codebase analysis
│   ├── prime-remote.md       # Prime from a remote/SSH codebase
│   ├── server-status.md      # Check server/service health
│   ├── sync-memories.md      # Sync agent memory across sessions
│   ├── validation/
│   │   ├── validate.md           # Run full validation suite
│   │   ├── code-review.md        # Technical code review
│   │   ├── code-review-fix.md    # Fix issues found in review
│   │   ├── execution-report.md   # Post-implementation report
│   │   └── system-review.md      # Implementation vs plan analysis
│   └── github_bug_fix/
│       ├── rca.md                # Root cause analysis for a GitHub issue
│       └── implement-fix.md      # Implement fix from RCA
├── rules/
│   ├── caddy.md
│   ├── docker.md
│   ├── git-conventions.md
│   ├── kubernetes.md
│   ├── n8n-workflows.md
│   ├── postgres.md
│   ├── python-fastapi.md
│   ├── toolchain.md
│   └── typescript-react.md
├── skills/
│   ├── agent-browser/SKILL.md    # Browser automation (Playwright-based CLI)
│   └── e2e-test/SKILL.md         # Full E2E test workflow using agent-browser
├── reference/
│   ├── fastapi-best-practices.md
│   ├── caddy-patterns.md
│   ├── uv-python-workflow.md
│   ├── deployment-best-practices.md
│   ├── sqlite-best-practices.md
│   ├── react-frontend-best-practices.md
│   ├── claude-hacks.md
│   └── testing-and-logging.md
├── docs/
│   └── CLAUDE_CODE_WORKFLOW.md   # Full workflow documentation
├── CLAUDE-template.md            # Blank CLAUDE.md template to copy per-project
└── PRD.md                        # Product Requirements Document

CLAUDE.md                         # Global context file — populate for your machine
README.md                         # This file

CLAUDE.md — Your Global Context File

CLAUDE.md in the repo root is your machine/identity context. Claude Code reads it automatically when you run claude from any directory that has it (or is symlinked to it).

Populate it once with your stack, active projects, and conventions. Use the template as a starting point:

cp .claude/CLAUDE-template.md CLAUDE.md
# Edit CLAUDE.md, then commit
git add CLAUDE.md && git commit -m "feat: populate CLAUDE.md for this machine"

Example content for a CogStack / self-hosted setup:

# CogStack — Claude Code Context

## Who I Am
Charles Vosloo, founder/CEO of CogStack, AI infrastructure consultancy, Johannesburg SA.

## Stack
- Python: uv exclusively (never bare pip)
- TypeScript, Postgres, Docker Compose
- Shell: zsh + tmux | Editor: Zed in vim mode
- Commits: conventional commits

## Active Projects
- CTIS: tender.cogstack.co.za — Next.js + FastAPI
- cogstack-leadgen: n8n + Notion CRM + Python scraper
- Hermes: ~/.hermes/ — v0.7.0, Telegram @CogHermes_bot

## Do Not
- Never pip install outside a project venv
- Never commit .env files
- Never operate git on /mnt/d/ paths (cold archive, 9P filesystem)

The PIV Loop

┌─────────┐     ┌─────────────┐     ┌──────────┐
│  PRIME  │ ──► │  IMPLEMENT  │ ──► │ VALIDATE │
└─────────┘     └─────────────┘     └──────────┘
     │                                    │
     └────────────────────────────────────┘
                    (iterate)

Phase	Commands	What Happens
Prime	`/prime`	Claude reads CLAUDE.md, PRD, and codebase structure
Implement	`/plan-feature`, `/execute`	Plan written to `.agents/plans/`, then executed
Validate	`/validation:validate`, `/validation:code-review`	Lint, test, review

Step-by-Step Workflow

1. Start a session

cd /your/project   # or ~/.hermes for Hermes work
claude

2. Prime Claude

/prime

Loads CLAUDE.md, PRD.md, and codebase structure into context. Run at the start of every session.

3. Plan a feature (or pass a spec doc directly)

/plan-feature Add user authentication

Or pass an existing spec/troubleshooting doc:

/plan-feature /home/charles/.hermes/docs/HermesV0.7setup.md

Claude writes a detailed plan to .agents/plans/<feature-name>.md.

4. Execute the plan

/execute .agents/plans/add-user-authentication.md

Claude works through every task, runs validation commands after each step, and reports what was created or modified.

5. Validate

/validation:validate
/validation:code-review

Fix issues:

/validation:code-review-fix

6. Commit

/commit

7. Repeat from step 3

Command Reference

Core PIV Loop

Command	Description
`/prime`	Load project context
`/prime-remote`	Prime from a remote/SSH codebase
`/plan-feature [description or path]`	Create implementation plan
`/execute [path-to-plan]`	Execute a plan

Validation

Command	Description
`/validation:validate`	Full validation suite
`/validation:code-review`	Technical review of changed files
`/validation:code-review-fix`	Fix issues found in review
`/validation:execution-report`	Post-implementation report
`/validation:system-review`	Implementation vs plan analysis

Bug Fixing

Command	Description
`/github_bug_fix:rca`	Root cause analysis for a GitHub issue
`/github_bug_fix:implement-fix`	Implement fix from RCA

Utilities

Command	Description
`/commit`	Atomic commit with conventional format
`/create-prd`	Generate PRD from conversation
`/create-rules`	Auto-generate CLAUDE.md from codebase
`/server-status`	Check server/service health
`/sync-memories`	Sync agent memory across sessions

Skills

Skill	Description
`agent-browser`	Playwright-based browser automation CLI
`e2e-test`	Full E2E test workflow with browser + DB validation

Per-Project Usage

To add this workflow to an existing project (without global symlinks):

git clone --depth 1 -b myworkshop https://github.com/journeyman33/claude-code-template /tmp/claude-template
cp -r /tmp/claude-template/.claude /your/project/
cp -r /tmp/claude-template/.agents /your/project/
cp /tmp/claude-template/.claude/CLAUDE-template.md /your/project/CLAUDE.md
rm -rf /tmp/claude-template

# Customise CLAUDE.md for this project
git add .claude/ .agents/ CLAUDE.md
git commit -m "feat: add Claude Code workflow"

Default Tech Stack

Layer	Default	Reference Doc
Backend	Python 3.12+, FastAPI, uv	`uv-python-workflow.md`, `fastapi-best-practices.md`
Database	Postgres (pgvector)	`sqlite-best-practices.md`
Frontend	React 18, Vite, Tailwind	`react-frontend-best-practices.md`
Reverse Proxy	Caddy	`caddy-patterns.md`
Deployment	Docker Compose	`deployment-best-practices.md`
Testing	pytest, Playwright	`testing-and-logging.md`
Workflows	n8n	`n8n-workflows.md`

Key Principles

Define before building — a vague PRD produces vague code
Plan before executing — the plan is the context that makes one-pass implementation possible
Validate frequently — don't let failures accumulate
Keep CLAUDE.md current — it is Claude's memory across sessions
Symlink, don't copy — one repo, available everywhere

Credits

A structured template for building applications with Claude Code using the PIV Loop workflow — Prime → Implement → Validate.

Clone this repo as the starting point for any new project. It provides slash commands, reference documentation, skills, and best practices for AI-assisted development.

What's Included

.agents/
└── plans/              # Feature implementation plans (generated by /plan-feature)

.claude/
├── commands/
│   ├── prime.md        # Load codebase context into Claude
│   ├── plan-feature.md # Create a detailed implementation plan
│   ├── execute.md      # Execute a plan step-by-step
│   ├── commit.md       # Atomic commit helper
│   ├── create-prd.md   # Generate a PRD from conversation
│   └── create-rules.md # Auto-generate CLAUDE.md from codebase analysis
│   ├── validation/
│   │   ├── validate.md         # Run full validation suite
│   │   ├── code-review.md      # Technical code review
│   │   ├── code-review-fix.md  # Fix issues found in review
│   │   ├── execution-report.md # Post-implementation report
│   │   └── system-review.md    # Implementation vs plan analysis
│   └── github_bug_fix/
│       ├── rca.md              # Root cause analysis for a GitHub issue
│       └── implement-fix.md    # Implement fix from RCA
├── skills/
│   ├── agent-browser/SKILL.md  # Browser automation (Playwright-based CLI)
│   └── e2e-test/SKILL.md       # Full E2E test workflow using agent-browser
├── reference/
│   ├── fastapi-best-practices.md
│   ├── caddy-patterns.md
│   ├── uv-python-workflow.md
│   ├── deployment-best-practices.md
│   ├── sqlite-best-practices.md
│   ├── react-frontend-best-practices.md
│   └── testing-and-logging.md
├── docs/
│   └── CLAUDE_CODE_WORKFLOW.md  # Full workflow documentation
├── CLAUDE-template.md           # Blank CLAUDE.md template
└── PRD.md                       # Product Requirements Document (fill this in)

CLAUDE.md                        # Project rules for Claude (fill this in)

Quick Start

New Project from This Template

# 1. Use as GitHub template (recommended) or clone manually
git clone https://github.com/YOUR_USERNAME/claude-code-workflow.git my-new-project
cd my-new-project

# 2. If cloned (not templated), reset git history
rm -rf .git
git init
git add .
git commit -m "feat: initial project from claude-code-workflow template"

# 3. Push to your own GitHub repo
gh repo create my-new-project --public --source=. --push

# 4. Start Claude Code
claude

Adding This Workflow to an Existing Project

# Clone just the .claude and .agents directories into your project
git clone --depth 1 https://github.com/YOUR_USERNAME/claude-code-workflow.git /tmp/claude-template
cp -r /tmp/claude-template/.claude /path/to/your/project/
cp -r /tmp/claude-template/.agents /path/to/your/project/
cp /tmp/claude-template/.claude/CLAUDE-template.md /path/to/your/project/CLAUDE.md
rm -rf /tmp/claude-template

# Customise CLAUDE.md for your project, then commit
git add .claude/ .agents/ CLAUDE.md
git commit -m "feat: add Claude Code workflow"

The PIV Loop

┌─────────┐     ┌─────────────┐     ┌──────────┐
│  PRIME  │ ──► │  IMPLEMENT  │ ──► │ VALIDATE │
└─────────┘     └─────────────┘     └──────────┘
     │                                    │
     └────────────────────────────────────┘
                    (iterate)

Phase	Commands	What Happens
Prime	`/prime`	Claude reads CLAUDE.md, PRD, and codebase structure
Implement	`/plan-feature`, `/execute`	Plan is written to `.agents/plans/`, then executed
Validate	`/validation:validate`, `/validation:code-review`	Lint, test, review

Step-by-Step Workflow

1. Define your project

Open Claude Code and describe what you want to build.

claude

2. Create a PRD

/create-prd

Claude interviews you and writes .claude/PRD.md — your project blueprint covering features, user stories, tech stack, and API design.

3. Set up CLAUDE.md

Either fill in .claude/CLAUDE-template.md manually, or let Claude generate it:

/create-rules

This analyses the codebase and writes a CLAUDE.md tailored to your project.

4. Prime Claude

/prime

Loads CLAUDE.md, PRD.md, and codebase structure into context. Run this at the start of every session.

5. Plan a feature

/plan-feature Add user authentication

Claude analyses the codebase, researches patterns, and writes a detailed plan to .agents/plans/add-user-authentication.md.

6. Execute the plan

/execute .agents/plans/add-user-authentication.md

Claude works through every task in the plan, runs validation commands after each step, and reports what was created or modified.

7. Validate

/validation:validate
/validation:code-review

Fix any issues:

/validation:code-review-fix

8. Commit

/commit

9. Repeat from step 5

Command Reference

Core PIV Loop

Command	Description
`/prime`	Load project context
`/plan-feature [description]`	Create implementation plan
`/execute [path-to-plan]`	Execute a plan

Validation

Command	Description
`/validation:validate`	Full validation suite
`/validation:code-review`	Technical review of changed files
`/validation:code-review-fix`	Fix issues found in review
`/validation:execution-report`	Post-implementation report
`/validation:system-review`	Implementation vs plan analysis

Bug Fixing

Command	Description
`/github_bug_fix:rca`	Root cause analysis for a GitHub issue
`/github_bug_fix:implement-fix`	Implement fix from RCA

Utilities

Command	Description
`/commit`	Atomic commit with conventional format
`/create-prd`	Generate PRD from conversation
`/create-rules`	Auto-generate CLAUDE.md

Skills

Skills are reusable workflows invoked from inside other commands or directly.

Skill	Description
`agent-browser`	Playwright-based browser automation CLI
`e2e-test`	Full E2E test workflow with browser + DB validation

Default Tech Stack

The reference docs are written for this stack. Swap them out for your own preferences.

Layer	Default	Reference Doc
Backend	Python 3.12+, FastAPI, UV	`uv-python-workflow.md`, `fastapi-best-practices.md`
Database	SQLite → Postgres	`sqlite-best-practices.md`
Frontend	React 18, Vite, Tailwind	`react-frontend-best-practices.md`
Reverse Proxy	Caddy	`caddy-patterns.md`
Deployment	Docker Compose	`deployment-best-practices.md`
Testing	pytest, Playwright	`testing-and-logging.md`

Customising for Your Stack

Different tech stack

Replace or add files in .claude/reference/. Reference them in CLAUDE.md under an "On-Demand Context" table so Claude knows when to read them.

Different branching strategy

Edit .claude/commands/commit.md to match your workflow (GitFlow, trunk-based, etc.).

Different test runner

Update .claude/commands/validation/validate.md to call your test commands.

Key Principles

Define before building — a vague PRD produces vague code
Plan before executing — the plan is the context that makes one-pass implementation possible
Validate frequently — don't let failures accumulate
Keep CLAUDE.md current — it is Claude's memory across sessions

Credits

Based on Cole Medin's AI Coding Workshop and updated with patterns from link-in-bio-page-builder.

Customised with Caddy, UV, and Docker Compose patterns for self-hosted deployments. Based on Cole Medin's AI Coding Workshop. Customised with Caddy, uv, Docker Compose, n8n, and self-hosted infrastructure patterns for the CogStack stack.

Name		Name	Last commit message	Last commit date
.agents/plans		.agents/plans
.claude		.claude
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

Claude Code Workflow Template

Global Installation (CogStack Setup)

What's Included

CLAUDE.md — Your Global Context File

The PIV Loop

Step-by-Step Workflow

1. Start a session

2. Prime Claude

3. Plan a feature (or pass a spec doc directly)

4. Execute the plan

5. Validate

6. Commit

7. Repeat from step 3

Command Reference

Core PIV Loop

Validation

Bug Fixing

Utilities

Skills

Per-Project Usage

Default Tech Stack

Key Principles

Credits

What's Included

Quick Start

New Project from This Template

Adding This Workflow to an Existing Project

The PIV Loop

Step-by-Step Workflow

1. Define your project

2. Create a PRD

3. Set up CLAUDE.md

4. Prime Claude

5. Plan a feature

6. Execute the plan

7. Validate

8. Commit

9. Repeat from step 5

Command Reference

Core PIV Loop

Validation

Bug Fixing

Utilities

Skills

Default Tech Stack

Customising for Your Stack

Different tech stack

Different branching strategy

Different test runner

Key Principles

Credits

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors