Workflows & Conventions

33 guideline files organized into 4 directories configure how AI agents work. Start with sensible defaults, customize as your project evolves.

The Core Development Flow

# 1. Define your vision
/project-brief          # Interactive Q&A creates docs/project-brief.md

# 2. Create feature specification
/spec                    # Creates pm/specs/SPEC-001-feature-name.md

# 3. Create work items
/issue "implement login" # Creates pm/issues/001-implement-login/TASK.md

# 4. Plan implementation
/plan 001               # Creates PLAN.md with TDD phases

# 5. Execute phases
/implement 001 --full   # Runs all phases with quality gates

# 6. Complete and merge
/complete 001           # Validates requirements met
/branch merge develop   # Merges to staging branch

File Structure

pm/ ├── specs/ │ └── SPEC-001-user-auth.md # Feature spec with acceptance criteria │ └── issues/ ├── 001-login-form/ │ ├── TASK.md # Requirements & acceptance criteria │ ├── PLAN.md # AI implementation phases │ └── WORKLOG.md # Implementation history │ └── 002-session-timeout/ ├── BUG.md # Bug report with reproduction steps ├── PLAN.md └── WORKLOG.md docs/ ├── project-brief.md # Your project vision ├── project/ │ ├── adrs/ # Architecture Decision Records │ └── research/ # Persistent research documents └── development/ ├── conventions/ # 7 files - Project conventions ├── workflows/ # 9 files - AI execution protocols ├── templates/ # 12 files - PM and doc templates └── misc/ # 5 files - Reference docs

Conventions (7 files)

Project-level standards that define how your codebase should look and behave.

coding-standards.md

Language-specific coding conventions, formatting rules, naming patterns

testing-strategy.md

Test types, coverage requirements, testing patterns

documentation-standards.md

Documentation requirements, formats, and locations

architectural-principles.md

Core architectural patterns and constraints

security-guidelines.md

Security requirements, OWASP compliance, auth patterns

ui-design-guidelines.md

Design system, component patterns, accessibility

versioning-and-releases.md

Semantic versioning rules, release process

Workflows (9 files)

AI execution protocols that define how commands and agents operate.

task-workflow.md

TDD phases (RED/GREEN/REFACTOR), quality gates, completion criteria

bug-workflow.md

Reproduction-first debugging, 5-step loop, fix validation

spike-workflow.md

Exploration planning, time-boxing, branch handling

pm-workflows.md

Issue management, spec lifecycle, plan structure

git-workflow.md

Three-branch model, commit conventions, merge rules

agent-coordination.md

Agent handoff patterns, orchestration, communication

quality-gates.md

Review thresholds, test requirements, checkpoint rules

worklog-format.md

WORKLOG entry formats (Standard, Troubleshooting, Research)

troubleshooting.md

Debugging strategies, common issues, escalation paths

Templates (12 files)

File templates for consistent document structure.

spec-template.md

Feature specification with acceptance criteria and scenarios

task-template.md

Task definition with requirements and completion criteria

bug-template.md

Bug report with reproduction steps and environment info

spike-template.md

Exploration issue with questions and success criteria

plan-template.md

Implementation plan with phases and checkpoints

adr-template.md

Architecture Decision Record with context and consequences

research-template.md

Persistent research document with findings and resources

project-brief-template.md

Project vision document structure

architecture-overview-template.md

System architecture documentation

note-template.md

General notes and documentation

epic-template.md

Epic definition for Jira integration

Key Workflows Explained

TDD Workflow (Tasks)

Phase Structure

  • X.RED - Write failing tests first. Checkpoint: tests FAIL
  • X.GREEN - Implement until tests pass. Checkpoint: tests PASS
  • X.REFACTOR - Clean up code. Checkpoint: review score >= 90

Bug Workflow

Reproduction-First Approach

  • Phase 1: Reproduce - Write a failing test that proves the bug exists
  • Phase 2: Fix - Implement fix, test passes, no regressions
  • Phase 3: Harden - Add edge case tests (optional)

Git Workflow

Three-Branch Model

  • feature/### - Work branches for tasks (auto-created by /implement)
  • develop - Staging branch, integration testing
  • main - Production-ready code only

Quality Gates

Enforcement Points

  • RED checkpoint - Tests must FAIL before implementation
  • GREEN checkpoint - Tests must PASS after implementation
  • REFACTOR checkpoint - Code review score must be >= 90
  • Merge validation - All phases complete, no failing tests

Customization

All guideline files are in your project at docs/development/. Edit them to match your team's preferences:

Common Customizations

  • Change review score threshold in quality-gates.md
  • Add language-specific rules to coding-standards.md
  • Modify branch naming in git-workflow.md
  • Adjust test coverage requirements in testing-strategy.md
  • Add security requirements to security-guidelines.md

After editing guidelines, use /refresh to ensure AI picks up your changes.