Setup

Config

Run

Report

Step-by-Step Guide

Zero to First Report

10 steps that walk you through the entire EDPA framework — from tool installation to a calibrated hour allocation report.

Start the guide

Prerequisites

Install GitHub CLI, Python 3.10+, and PyYAML. Verify your GitHub login with project scope.

terminal

# GitHub CLI — authenticate with project scope
gh auth login
gh auth refresh -s project,read:project

# Python dependencies
pip install pyyaml

# Verify
python3 --version   # >= 3.10
gh --version        # >= 2.40

Expected output

✓ Logged in to github.com as your-user
✓ Token scopes: repo, project, read:project
✓ pyyaml installed
Python 3.12.1
gh version 2.44.1

Next step →

Create Repository

Create a new GitHub repository in your organization. EDPA requires an org repo (not personal) for Issue Types and GitHub Projects.

terminal

# Create a private org repo
gh repo create ORG/project-name \
  --private --clone

cd project-name

Expected output

✓ Created repository ORG/project-name on GitHub
✓ Cloned to ./project-name

Back Next step →

Install EDPA

One command installs the EDPA plugin into .claude/edpa/ and creates the .edpa/ directory structure. No manual copying needed.

terminal

curl -fsSL https://edpa.technomaton.com/install.sh | sh

Expected output

EDPA Installer
==============
Downloading EDPA plugin...
✓ Plugin installed to .claude/edpa/
✓ Created .edpa/ structure:
  .claude/edpa/    ← scripts, skills, hooks
  .edpa/config/    ← team and iteration config
  .edpa/backlog/   ← work items (per-item YAML)
  .edpa/reports/   ← generated reports

Next: open Claude Code and run /edpa setup

Back Next step →

/edpa setup

One command configures everything — team, Issue Types, GitHub Project with 8 views, SAFe status fields, custom fields, sub-issue hierarchy, and CI workflows.

claude code (recommended)

/edpa setup "Project Name"
# Claude Code handles everything interactively

terminal

# Manual alternative (if not using Claude Code):
# 1. Edit .edpa/config/people.yaml (team, roles, FTE, capacity)
# 2. Issue Types:
python3 .claude/edpa/scripts/issue_types.py setup --org ORG
# 3. GitHub Project:
python3 .claude/edpa/scripts/project_setup.py --org ORG --repo project-name
# 4. Views:
python3 .claude/edpa/scripts/create_project_views.py

Expected output

✓ Team: 3 members configured (2.8 FTE)
✓ Issue Types: Initiative, Epic, Feature, Story, Defect, Task
✓ GitHub Project created (#4)
✓ Status fields: Initiative, Epic, Feature, Story (SAFe workflows)
✓ Fields: Job Size, BV, TC, RR, WSJF Score, Team
✓ 8 views: All Items, Board, Epics, Features, WSJF,
           Current Iteration, My Work, Roadmap
✓ Branch-check CI workflow installed
✓ Config saved to .edpa/config/edpa.yaml

⚠ Enable in GitHub Project → Workflows:
  ✓ Item added → Set status "Funnel"
  ✓ Auto-add issues from linked repo
  ✗ NEVER enable auto-archive!

Back Next step →

Populate Backlog

Create YAML files in .edpa/backlog/ — one file per item. Hierarchy: Initiative > Epic > Feature > Story. WSJF is calculated automatically.

terminal

# .edpa/backlog/stories/S-1.yaml
id: S-1
type: Story
title: "Implement login endpoint"
js: 5              # Job Size (Fibonacci)
bv: 8              # Business Value
tc: 5              # Time Criticality
rr: 3              # Risk Reduction
status: Backlog
parent: F-1      # Parent Feature
assignee: jnovak
iteration: PI-2026-1.1

# Validate backlog
python3 .claude/edpa/scripts/backlog.py validate
python3 .claude/edpa/scripts/backlog.py tree

Expected output

✓ Backlog valid (12 items, 0 errors)

I-1: Medical Platform
└── E-1: Data Processing Pipeline
    ├── F-1: Authentication (JS=8, WSJF=2.0)
    │   ├── S-1: Login endpoint (JS=5) ← jnovak
    │   └── S-2: Token refresh (JS=3) ← emala
    └── F-2: Data Import (JS=13, WSJF=1.8)
        ├── S-3: CSV parser (JS=5) ← emala
        └── S-4: Validation (JS=3) ← pkral

Back Next step →

Team Starts Working

The team works using standard GitHub flow — branch naming conventions, commits referencing items, PRs and code review. EDPA tracks everything automatically.

terminal

# Branch naming (CI enforces format)
git checkout -b feature/S-1-login-endpoint

# Commit referencing item
git commit -m "feat(S-1): implement JWT login"

# Pull Request
gh pr create \
  --title "S-1: Login endpoint" \
  --body "Implements JWT auth flow" \
  --assignee jnovak

Expected output

Branch: feature/S-1-login-endpoint
Commits: 4 (linked to S-1)
PR #42: "S-1: Login endpoint"
  → Review requested: pkral
  → Status: Approved ✓ → Merged

Evidence detected:
  jnovak: assignee (+4), PR author (+2), commits (+1)
  pkral:  PR reviewer (+1)

Back Next step →

End of Iteration

At iteration end, the EDPA engine reads evidence from backlog YAML files and proportionally allocates hours based on actual work.

claude code (recommended)

/edpa close-iteration PI-2026-1.1
# Claude Code fetches evidence and computes allocation

terminal

python3 .claude/edpa/scripts/engine.py \
  --edpa-root .edpa \
  --iteration PI-2026-1.1

# The engine automatically:
# 1. Reads evidence from .edpa/backlog/ YAML files
# 2. Computes contribution weight (CW)
# 3. Allocates hours: Score / Total × Capacity
# 4. Generates reports

Expected output

EDPA Engine v1.4.0-beta — PI-2026-1.1
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Team:     3 members, 2.8 FTE
Capacity: 448 hours (2 weeks)

Allocation:
  jnovak  │████████████████░░│ 178.2h (39.8%)
  emala   │█████████████░░░░░│ 142.6h (31.8%)
  pkral   │████████████░░░░░░│ 127.2h (28.4%)
                        Total: 448.0h ✓
Invariants: ALL PASSED

Back Next step →

Reports & Timesheets

EDPA generates per-person timesheets, per-item cost allocation, JSON exports, and frozen snapshots. All auditable and reproducible.

claude code (recommended)

/edpa reports
# Claude Code generates all reports and timesheets

terminal

# Generated files
.edpa/reports/
├── iteration-PI-2026-1.1/
│   ├── vykaz-jnovak.md      # per-person timesheet
│   ├── vykaz-emala.md
│   ├── vykaz-pkral.md
│   ├── edpa_results.json    # machine-readable
│   └── summary.xlsx         # Excel export
.edpa/snapshots/
└── iteration-PI-2026-1.1.json  # frozen snapshot

Expected output

Per-person timesheet (vykaz-jnovak.md):
┌──────────┬────────┬────────┬────────┐
│ Person   │ Hours  │ Share  │ Items  │
├──────────┼────────┼────────┼────────┤
│ jnovak   │ 178.2  │ 39.8%  │ 7      │
│ emala    │ 142.6  │ 31.8%  │ 5      │
│ pkral    │ 127.2  │ 28.4%  │ 6      │
├──────────┼────────┼────────┼────────┤
│ TOTAL    │ 448.0  │ 100%   │ 18     │
└──────────┴────────┴────────┴────────┘

Back Next step →

Retrospective + Calibration

Compare EDPA outputs against ground truth. evaluate_cw.py computes MAD, correlation, and identifies outliers.

claude code (recommended)

/edpa calibrate
# Claude Code runs calibration and shows MAD results

terminal

# Ground truth comparison
python3 .claude/edpa/scripts/evaluate_cw.py \
  --iteration PI-2026-1.1 \
  --ground-truth .edpa/data/ground_truth.csv

# MAD < 0.05 → excellent calibration
# MAD 0.05-0.10 → good calibration
# MAD > 0.10 → weight adjustment needed

Expected output

Evaluation: PI-2026-1.1
━━━━━━━━━━━━━━━━━━━━━━━
Pearson r:     0.94
MAD:           0.032  ← excellent calibration
Max deviation: 0.061 (pkral)

Verdict: EXCELLENT
No weight adjustment needed.

Back Next step →

Next PI

Repeat for each iteration. With every cycle, calibration improves. Target: predictability > 80%, MAD < 0.05 by the third PI.

claude code (recommended)

/edpa close-iteration PI-2026-1.2
# Next iteration — same workflow

terminal

# New iteration
python3 .claude/edpa/scripts/engine.py \
  --edpa-root .edpa \
  --iteration PI-2026-1.2

# Compare iteration results in .edpa/reports/

Expected output

Trend: PI-2026-1.1 → PI-2026-1.4
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MAD:            0.032 → 0.018  ↓ improving
Predictability: 78%   → 91%   ↑ on target
Correlation:    0.94  → 0.98  ↑ strong

Status: Mature — framework calibrated.

Back Done — back to EDPA