Skip to content

jersal-project-template

The template repository provides a standardized starting point for all new Jersal projects. Every project created from this template inherits a planning-first workflow, consistent conventions, and CI enforcement.

Purpose

Instead of setting up each new project from scratch, the template ensures:

  • Planning-first workflow -- Implementation code is blocked by CI until planning is approved
  • Consistent conventions -- Branch naming, commit messages, merge strategy, and editor config are pre-configured
  • Documentation structure -- A docs/ folder with planning phases and a project health checklist
  • CI/CD foundation -- Planning gate workflow and auto-assign for AI-assisted reviews
  • Convention compliance -- Aligned with the Jersal standards defined in this hub

How to use

  1. Navigate to the template repository on GitHub
  2. Click Use this template > Create a new repository
  3. Name the repository following the naming conventions
  4. Clone the new repository locally
  5. Run ./scripts/setup-repo.sh to configure GitHub repository settings (merge strategy, branch rulesets, labels, security)
  6. Fill in placeholder values in README.md, SECURITY.md, CODE_OF_CONDUCT.md
  7. Update .github/CODEOWNERS with the appropriate owners
  8. Add repository secrets if needed
  9. Connect to shared infrastructure via Terraform remote state (see access contracts)

What's included

Repository structure

project-repo/
├── .github/
│   ├── CODEOWNERS                          # Code ownership rules
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug-report.md                   # Bug report template
│   │   └── product-vision.md               # Product vision issue template
│   ├── PULL_REQUEST_TEMPLATE/
│   │   ├── pull_request_template.md        # Default PR template
│   │   └── planning-pr.md                  # Planning PR template
│   ├── copilot-instructions.md             # AI assistant guidelines
│   ├── instructions/
│   │   └── planning.instructions.md        # AI planning review instructions
│   └── workflows/
│       ├── planning-gate.yml               # Blocks code until planning approved
│       └── auto-assign-copilot-planning.yml
├── docs/
│   ├── planning/
│   │   ├── README.md                       # Planning workflow overview
│   │   ├── idea.md                         # Problem, users, outcomes, scope
│   │   ├── specification.md                # User stories, requirements, risks
│   │   ├── high-level-plan.md              # Architecture, milestones, work breakdown
│   │   └── planning-status.yml             # Machine-readable phase tracker
│   └── project-health-checklist.md         # 9-section audit checklist
├── scripts/
│   └── setup-repo.sh                       # Post-template GitHub settings config
├── .editorconfig                           # Editor configuration
├── .env.example                            # Environment variable template
├── .gitignore
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md                         # Contribution guidelines
├── LICENSE                                 # MIT License
├── README.md
└── SECURITY.md

Planning-first workflow

The template's core feature is a planning gate that blocks implementation code until planning is complete:

graph LR
    A["Product Vision<br/>(issue)"] --> B["Idea"]
    B --> C["Specification"]
    C --> D["High-Level Plan"]
    D --> E["plan-approved"]
    E --> F["Implementation<br/>PRs allowed"]
Phase File What it captures
Idea docs/planning/idea.md Problem, target users, outcomes, scope, AI sparring results
Specification docs/planning/specification.md User roles, user stories, functional/non-functional requirements, risks
High-Level Plan docs/planning/high-level-plan.md Architecture overview, tech stack, milestones, work breakdown, dependencies
Status tracking docs/planning/planning-status.yml Machine-readable phase: pending > idea-approved > spec-approved > plan-approved

The planning-gate.yml CI workflow reads planning-status.yml. If the phase is not plan-approved, any PR that touches application code directories (src/, tests/, lib/, packages/, app/, apps/, services/, functions/) is blocked.

Project health checklist

docs/project-health-checklist.md is a 9-section, ~75-item audit covering:

  1. Repository foundations
  2. CI/CD pipeline
  3. Code quality and linting
  4. Testing
  5. Security
  6. Documentation
  7. Project governance and conventions
  8. Dependency management
  9. Containerization and infrastructure

With a prioritization tier system: Tier 1 (trust blockers), Tier 2 (quality gaps), Tier 3 (maturity signals).

Setup script

scripts/setup-repo.sh configures GitHub repository settings via the gh CLI:

Setting Value
Merge strategy Squash only (PR title + body becomes commit message)
Branch cleanup Auto-delete head branches after merge
Branch ruleset PR required, CODEOWNERS review, dismiss stale reviews, resolve conversations
Status checks planning-gate must pass
Linear history Enforced (no merge commits)
Force push / deletion Blocked on default branch
Wiki Disabled (use docs/ instead)
Security Vulnerability alerts + automated fixes enabled
Labels Standard set (bug, feature, size/xs-xl, etc.)

Conventions enforced

The template pre-configures conventions that align with the hub standards:

Convention Enforcement Reference
Branch naming (<type>/<description>) Documented in CONTRIBUTING.md Naming conventions
Commit messages (Conventional Commits) Documented in CONTRIBUTING.md Naming conventions
Squash merges only setup-repo.sh configures GitHub Architecture patterns
Linear history Branch ruleset Architecture patterns
.editorconfig UTF-8, LF, 2-space indent (4 for Python/C#) Coding conventions
AI instructions .github/copilot-instructions.md Clarity over creativity, no guessing

Relationship to the hub

The template provides project-level documentation structure. This hub provides organization-level documentation:

Scope Location Examples
Organization-wide This hub Standards, ADRs, project registry, shared infra docs
Project-specific Each project's docs/ folder Planning docs, health checklist, project architecture

Project pages in the hub's project registry link to each project's repository documentation for detailed information.