Global Workflow & Standards

Global Workflow & Standards

Last Updated: 29/12/2025 Version: 1.3.1 Maintained By: Development Team Language: British English (en_GB) Timezone: Europe/London

---

Table of Contents

• Table of Contents
• 1. Localisation
• 2. Repository Setup
  • SSH Cloning Requirement
  • Setting Up SSH
  • Converting HTTPS to SSH
• 3. Branch Strategy
  • Required Core Branches
  • User Story Branch Naming
  • Hotfix Branch Naming
  • Branch Flow
• 4. Git Protocol
  • Commit Message Template
  • Commit Types
  • Commit Rules
• 5. Pull Request Management
  • Using GitHub CLI (gh)
    • Creating PRs
    • Reviewing PRs
    • Managing PRs
  • PR Title Format
  • PR Body Template
  • Client Acceptance/Rejection (Staging → Main)
    • Accepting Changes
    • Rejecting Changes
• 6. Semantic Versioning
  • Version Format
  • Pre-Commit Requirements
• 7. Documentation Standards
  • Markdown Generation Guidelines
    • Table of Contents
    • Text Formatting
    • Lists
    • Tables
    • Code Blocks
    • Headings
    • Horizontal Rules
    • Best Practices
  • Bug Fix Documentation
• 8. Code Comment Standards
  • File Headers
  • Docstrings
  • No Pronouns Rule

---

0. Plugin Directory Discovery

Every agent must complete this step before referencing any plugin file — example files, templates, or any path under the syntek-dev-suite installation.

The plugin may be installed at any path (local clone, SSH mount, ~/.claude/plugins/, or a custom location). Never assume a fixed path.

Locating SYNTEK_DIR

Search for plugins/project-tool.py using the Glob tool in this order:

1. ~/.claude/plugins/syntek-dev-suite/plugins/project-tool.py
2. ~/.claude/plugins/**/plugins/project-tool.py
3. ~/Repos/**/syntek-dev-suite/plugins/project-tool.py
4. ~/**/syntek-dev-suite/plugins/project-tool.py

Once found, derive SYNTEK_DIR as the directory two levels above project-tool.py — that is, the syntek-dev-suite root containing plugins/, examples/, templates/, and config.json.

Use $SYNTEK_DIR as the base for all plugin file references throughout the agent's work:

$SYNTEK_DIR/examples/authentication/PASSWORD-VALIDATION.md
$SYNTEK_DIR/examples/setup/CODING-PRINCIPLES.md
$SYNTEK_DIR/templates/tall-project.md

If the plugin cannot be found at any of those locations, ask the user:

Could not locate the syntek-dev-suite plugin directory.
Please confirm the plugin is installed and provide the path, or run:
  find ~ -name "project-tool.py" -path "*/syntek-dev-suite/*" 2>/dev/null

---

1. Localisation

Setting	Value
Locale	British English (en-GB)
Spelling	Use 's' not 'z' (optimise, organise, behaviour)
Vocabulary	postcode, CV, holiday, mobile
Currency	GBP (£) with format £1,234.56
Date Format	DD/MM/YYYY
Time Format	24-hour clock (HH:MM)
Timezone	Europe/London

Code Syntax Exception: Keep US English for reserved words (CSS color, PHP function), but use GB English for variable names ($colourPalette) and user-facing copy.

---

2. Repository Setup

SSH Cloning Requirement

CRITICAL: All developers MUST clone repositories using SSH, not HTTPS.

# CORRECT - Use SSH
git clone [email protected]:organisation/repository.git

# INCORRECT - Do NOT use HTTPS
git clone https://github.com/organisation/repository.git

Why SSH:

• Enables proper commit author tracking
• Simplifies authentication (no password prompts)
• Required for signed commits
• Better security with key-based authentication

Setting Up SSH

1. Generate SSH key (if not already done):

   ssh-keygen -t ed25519 -C "[email protected]"
   

2. Add SSH key to ssh-agent:

   eval "$(ssh-agent -s)"
   ssh-add ~/.ssh/id_ed25519
   

3. Add public key to GitHub:

   • Copy: cat ~/.ssh/id_ed25519.pub
   • Add at: GitHub → Settings → SSH and GPG keys → New SSH key

4. Test connection:

   ssh -T [email protected]
   

Converting HTTPS to SSH

If a repository was cloned with HTTPS, convert it:

git remote set-url origin [email protected]:organisation/repository.git

---

3. Branch Strategy

Required Core Branches

Every project MUST have these protected branches:

Branch	Purpose	Protected	Deploy Target
main or master	Production-ready code	Yes	Production
staging	Client review and acceptance	Yes	Staging
dev	Integration and final testing	Yes	Development
testing	QA and automated testing	Yes	Testing

User Story Branch Naming

All feature work uses user story branches:

us<number>/<short-description>

Examples:

• us001/user-authentication
• us015/payment-integration
• us042/api-rate-limiting

Rules:

• User story number is zero-padded to 3 digits (us001, us042, us100)
• Description uses kebab-case (lowercase with hyphens)
• Description should be 2-4 words maximum

Hotfix Branch Naming

For critical production fixes:

hotfix/<issue-number>-<short-description>

Examples:

• hotfix/123-login-crash
• hotfix/456-payment-timeout

Branch Flow

us###/feature → testing → dev → staging → main

From	To	Condition	On Rejection
us###/feature	testing	Developer tests pass	Fix in feature branch
testing	dev	QA tests pass	Fix and re-submit
dev	staging	Integration tests pass	Fix and re-submit
staging	main	Client accepts	Back to us###/feature

---

4. Git Protocol

Commit Message Template

<type>(<scope>): <Description> - <Summarise>

<Body - What was changed and why>

Files Changed:
- <app-name/folder/file>

Still to do:
- <Task 1>
- <Task 2>

Version: <old-version> → <new-version>

Commit Types

Type	Use For
feat	New feature
fix	Bug fix
docs	Documentation only
style	Formatting, no logic change
refactor	Code restructure, no feature change
test	Adding/updating tests
chore	Build, config, dependencies

Commit Rules

1. Imperative mood: "Add feature" not "Added feature"
2. Version update: Include version change in commit
3. Changelog first: Update CHANGELOG.md before committing
4. No filler: Output ONLY the commit message code block

---

5. Pull Request Management

Using GitHub CLI (gh)

CRITICAL: All PR operations MUST use the gh CLI tool for consistency and automation.

Creating PRs

# Create PR from current branch to testing
gh pr create --base testing --title "[US001] feat(auth): Add login" --body "..."

# Create PR with template
gh pr create --base testing --title "[US001] feat(auth): Add login" --body-file .github/PULL_REQUEST_TEMPLATE.md

Reviewing PRs

# List open PRs
gh pr list

# View PR details
gh pr view <number>

# View PR diff
gh pr diff <number>

# Add review comment
gh pr review <number> --comment --body "Comment text"

# Approve PR
gh pr review <number> --approve --body "Approved: All tests pass"

# Request changes
gh pr review <number> --request-changes --body "Needs fixes: ..."

Managing PRs

# Merge PR (after approval)
gh pr merge <number> --merge

# Close PR without merging (rejected)
gh pr close <number> --comment "Rejected: Reason..."

# Reopen PR
gh pr reopen <number>

# Check PR status
gh pr status

PR Title Format

[<branch-type>] <type>(<scope>): <Description>

Examples:

• [US001] feat(auth): Add user login functionality
• [HOTFIX] fix(payment): Resolve checkout timeout
• [TESTING→DEV] feat(auth): User authentication module

PR Body Template

## Summary

- <Bullet point 1: What this PR does>
- <Bullet point 2: Key changes>
- <Bullet point 3: Any notable decisions>

## Changes

### Added
- <New feature or file>

### Changed
- <Modified functionality>

### Fixed
- <Bug fix>

## Version

**Previous:** `X.Y.Z`
**New:** `X.Y.Z`
**Increment Type:** MAJOR | MINOR | PATCH

## Commits Included

| Commit | Type | Description        |
| ------ | ---- | ------------------ |
| abc123 | feat | Add login form     |
| def456 | fix  | Correct validation |

## Test Plan

- [ ] <How to test change 1>
- [ ] <How to test change 2>
- [ ] Unit tests pass
- [ ] Integration tests pass

## Checklist

- [ ] Code follows project style guide
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
- [ ] Version files updated
- [ ] No secrets or credentials in code

## Related Issues

Closes #<issue-number>

Client Acceptance/Rejection (Staging → Main)

Accepting Changes

# Approve and merge to main
gh pr review <number> --approve --body "Client accepted: Ready for production"
gh pr merge <number> --merge

Rejecting Changes

# Request changes with rejection reason
gh pr review <number> --request-changes --body "Client rejected: <detailed reason>"

# Close the PR
gh pr close <number> --comment "Rejected by client. Creating fix branch from original US branch."

After rejection:

1. Create new branch from original us###/feature
2. Implement fixes
3. Re-submit through full flow: testing → dev → staging

---

6. Semantic Versioning

Version Format

MAJOR.MINOR.PATCH

Type	When to Increment	Example
MAJOR	Breaking changes	1.0.0 → 2.0.0
MINOR	New features (backwards compatible)	1.0.0 → 1.1.0
PATCH	Bug fixes (backwards compatible)	1.0.0 → 1.0.1

Pre-Commit Requirements

CRITICAL: Before EVERY commit:

1. Determine version increment (MAJOR/MINOR/PATCH)
2. Update all version files
3. Update CHANGELOG.md
4. Stage version and changelog files

---

7. Documentation Standards

Standard	Value
Format	Markdown (*.md)
Location	docs/ folder
Filenames	CAPITALISED with lowercase .md extension
Required	Table of Contents in all docs
Extension	Markdown All in One (yzhang.markdown-all-in-one)

Markdown Generation Guidelines

When generating markdown documentation, follow these standards for compatibility with the Markdown All in One extension:

Table of Contents

1. Placement: After document title and introduction, before main content
2. Format: Unordered list with - marker
3. Heading: Use ## Table of Contents
4. Indentation: 2 spaces per nesting level
5. Links: Use anchor link format [Text](#heading-slug)
6. Slug Format: Lowercase, hyphens for spaces, remove special chars

Example:

## Table of Contents

- [Main Title](#main-title)
  - [Table of Contents](#table-of-contents)
  - [Section 1](#section-1)
    - [Subsection 1.1](#subsection-11)

Text Formatting

Format	Syntax	Example
Bold	**text**	**important**
Italic	*text*	*emphasise*
Strikethrough	~~text~~	~~deprecated~~
Inline code	`code`	`function()`

Lists

Unordered Lists:

• Use - marker consistently
• 2 spaces for indentation

- Item 1
  - Nested item 1.1
  - Nested item 1.2
- Item 2

Ordered Lists:

• Use 1. marker for all items (auto-renumbering)
• 3 spaces for indentation

1. First step
   1. Sub-step 1.1
   1. Sub-step 1.2
1. Second step

Task Lists:

• Use for checklists and action items
• Format: - [ ] for incomplete, - [x] for complete

- [ ] Task to do
- [x] Completed task

Tables

Use GitHub Flavoured Markdown table syntax:

| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Value 1  | Value 2  | Value 3  |

Alignment:

• Left: |:---------|
• Centre: |:--------:|
• Right: |---------:|

Code Blocks

Fenced Code Blocks: Always specify language for syntax highlighting:

\`\`\`typescript
const example = "code";
\`\`\`

Common Languages: python, typescript, javascript, bash, json, sql, php, dart, html, css

Headings

Hierarchy:

• # Title - Document title (once per file)
• ## Section - Main sections
• ### Subsection - Subsections
• #### and beyond - As needed (avoid excessive nesting)

Excluding from TOC: Add <!-- omit in toc --> to exclude heading:

## Internal Notes <!-- omit in toc -->

Horizontal Rules

Use --- for horizontal rules between major sections.

Best Practices

1. Consistency: Use same syntax throughout (e.g., **bold** not __bold__)
2. British English: Follow CLAUDE.md localisation settings
3. Blank Lines: Add blank lines before/after headings, code blocks, tables
4. Line Length: Keep lines under 120 characters where practical
5. TOC Inclusion: Always include TOC section; extension handles updates for users

Bug Fix Documentation

CRITICAL: All bug fixes (on user story branches or hotfix branches) MUST be documented in docs/BUGS/.

See the /debug agent for the required documentation format. Bug documentation MUST include:

• Root cause analysis
• How the fix resolves the issue
• Prevention recommendations
• Regression test requirements

---

8. Code Comment Standards

All agents writing code MUST follow these documentation rules:

File Headers

Every file MUST have a header comment explaining its purpose.

Docstrings

Every public function/method MUST have a docstring with:

• Description of what the function does
• Parameters with types
• Return value with type
• Exceptions thrown

No Pronouns Rule

CRITICAL: Never use pronouns referring to code in comments.

Do	Don't
The function validates input	It validates the input
Returns the user object	Returns this
The service handles authentication	We handle auth here