JS-290 · Lesson 4 of 12 · 26 min
Project planning and team workflow
▶ Video coming soon A video version of this lesson is on the way.
Tuesday, April 3, 2029 is the first day of real building, and Mira wants the team to start it with a plan everyone believes. In earlier blocks the plan was simple because Mira worked alone with a mentor. Now three people will change the same code every day, two of them in their first months as developers, and the client expects something useful in eight weeks. This lesson is about the work around the code: sizing stories, planning sprints, keeping work visible, branching and reviewing, and deciding together what *done* means.
Gareth's view is that process should be the smallest amount that lets the team see problems early. A three-person team does not need a project manager, a ticketing system with forty fields or a two-hour planning meeting. It does need to know what each person is doing, what is blocked, whether the release is on track, and what every change must pass before it is merged. The team borrows a few pieces from Scrum and Kanban and drops the rest.
Scrum-lite: sprints, reviews and retrospectives
From Scrum the team takes the sprint: a fixed period, here two weeks, at the end of which the team shows working software and decides what comes next. Each sprint starts with sprint planning, where the team picks stories from the top of the priority list that it believes it can finish, and ends with a sprint review, where the team demonstrates what was finished to Lucy and Rosa, and a retrospective, where the team talks about how it worked and agrees one or two changes. In between there is a short stand-up each morning: what I did yesterday, what I am doing today, and what is in my way.
The team drops the parts that suit larger groups. There is no separate Scrum Master; Mira runs the meetings. There is no product owner in the formal sense; Lucy decides priorities, with Rosa consulted on anything about receiving, and Mira keeps the list in order between conversations. Stand-ups are ten minutes at 9:15, standing at the whiteboard, and they are allowed to be shorter.
| Period | Dates (2029) | Goal |
|---|---|---|
| Discovery and design | Mar 13 – Apr 2 | Problem, stories, architecture, plan |
| Sprint 1 | Apr 3 – Apr 13 | Sign-in works; a donor can post an offer; a driver can see it |
| Sprint 2 | Apr 16 – Apr 27 | Claiming with all rules; pickup done; receiving with weight and temperature |
| Sprint 3 | Apr 30 – May 11 | Lucy's views, monthly totals, offline pickup, should-haves |
| Hardening and release | May 14 – May 25 | Security and accessibility fixes, staging, production |
| Demo and retrospective | May 31 – Jun 1 | Show the result; learn from the project |
Sprint 1 starts on a Tuesday because Monday, April 2, is Easter Monday, which Brightwater gives as a holiday. Each sprint goal is written as an outcome a user could see, not as a list of tasks. If the team finishes the stories but the goal is not met, the sprint did not succeed, and the review will say so.
Sizing stories with points
To plan a sprint, the team needs some idea of how big each story is. Hours are tempting but misleading: people are bad at estimating absolute time and good at comparing. So the team sizes stories in story points, a relative measure. They pick a small, well-understood story as a reference, *the driver sees an offer's pickup instructions*, and call it 2 points. Every other story is sized by comparison: about the same, about twice as big, much bigger. The allowed sizes are 1, 2, 3, 5, 8 and 13, a sequence based on Fibonacci numbers, because the gaps grow as stories get bigger, which matches how uncertainty grows too.
To avoid anchoring on whoever speaks first, the team uses planning poker. Each person picks a card privately, everyone shows at once, and if the numbers differ, the highest and lowest explain their reasoning before the team votes again. The discussion is the point. Twice in the first session, Tavish's high card came from something the others had missed, such as donors with two locations.
// Planning poker: reveal, discuss, repeat until the cards are within one step.
const scale = [1, 2, 3, 5, 8, 13];
const step = (n) => scale.indexOf(n);
function settled(cards) {
const steps = cards.map(step);
return Math.max(...steps) - Math.min(...steps) <= 1;
}
const rounds = {
'claim run with rules': [[3, 8, 5], [5, 8, 5]],
'receive and log': [[5, 5, 3]],
'monthly totals': [[2, 5, 13], [2, 3, 3]],
};
for (const [story, history] of Object.entries(rounds)) {
history.forEach((cards, i) => {
const done = settled(cards);
const size = done ? Math.max(...cards) : '-';
console.log(`${story.padEnd(22)} round ${i + 1}: ${cards.join(' ')} ${done ? 'settled at ' + size : 'discuss'}`);
});
}claim run with rules round 1: 3 8 5 discuss claim run with rules round 2: 5 8 5 settled at 8 receive and log round 1: 5 5 3 settled at 5 monthly totals round 1: 2 5 13 discuss monthly totals round 2: 2 3 3 settled at 3
What this code does
Each card is converted to its position on the scale, and a round counts as settled when all the cards are within one position of each other. A settled story takes the highest card, which is a cautious rule many teams use when the difference is small. Rounds that are not settled are marked for discussion, and the history shows how a second round usually closes the gap.
From people to capacity
Points only help with planning if the team knows how many it can finish in a sprint. A team with history uses its velocity, the points actually finished in recent sprints. This team has no history, so Mira estimates capacity from availability and then corrects it after the first sprint. She counts each person's days on the project in a sprint, multiplies by a focus factor for meetings, reviews, questions and interruptions, and converts to points using the team's rough sense that a 2-point story takes about a day and a half of focused work.
// Capacity for a two-week sprint, from availability.
const days = { Mira: 8, Odalys: 7, Tavish: 7 }; // college, mentoring and support take the rest
const focus = 0.6; // share of a day spent on sprint stories
const daysPerPoint = 0.75; // a 2-point story is about 1.5 focused days
const personDays = Object.values(days).reduce((a, b) => a + b, 0);
const focusedDays = personDays * focus;
const points = Math.round(focusedDays / daysPerPoint);
console.log(`person-days ${personDays}, focused days ${focusedDays.toFixed(1)}, points ${points}`);
console.log(`three sprints: ${points * 3} points`);person-days 22, focused days 13.2, points 18 three sprints: 54 points
What this code does
The person-days are added up and multiplied by the focus factor, which accounts for the time that is not spent on sprint stories. Dividing by the days a point takes converts focused days to points, and the result is rounded to a whole number. The total for three sprints is the 54 points the team used when checking the MoSCoW plan in lesson 2.
The estimate is only a starting point. At the end of Sprint 1 the team finishes 15 points instead of 18, because Theo's token endpoint took longer than planned and Odalys and Tavish spent a day pairing on the first migration. Mira lowers the plan for Sprint 2 to 16 points and moves one could-have below the line. Adjusting the plan from evidence, early and calmly, is the whole value of measuring velocity.
Making work visible: the board
Between planning meetings, the work lives on a Kanban board, an idea the team takes from Kanban. The board has columns for each stage of work, *Ready*, *In progress*, *In review*, *Done*, and every story or task is a card that moves from left to right. A shared board in the repository's project view replaces most status questions: anyone can see what is happening without asking.
The most important Kanban idea is the work-in-progress limit, or WIP limit. The *In progress* column may hold at most three cards, one per person, and *In review* at most two. When a column is full, nobody starts something new; they help finish what is already there, usually by reviewing. WIP limits feel slow at first and are faster in practice, because half-finished work is worth nothing to users and every extra item a person juggles slows all of them down.
// Check WIP limits and work out how long finished cards took.
const limits = { 'in progress': 3, 'in review': 2 };
const cards = [
{ id: 'RR-12', col: 'in progress', started: 3 },
{ id: 'RR-14', col: 'in progress', started: 4 },
{ id: 'RR-15', col: 'in progress', started: 5 },
{ id: 'RR-16', col: 'in progress', started: 5 },
{ id: 'RR-09', col: 'in review', started: 2 },
{ id: 'RR-05', col: 'done', started: 1, finished: 3 },
{ id: 'RR-07', col: 'done', started: 1, finished: 4 },
{ id: 'RR-08', col: 'done', started: 2, finished: 7 },
];
for (const [col, limit] of Object.entries(limits)) {
const n = cards.filter((c) => c.col === col).length;
console.log(`${col}: ${n} of ${limit}${n > limit ? ' OVER LIMIT, finish something first' : ''}`);
}
const done = cards.filter((c) => c.col === 'done');
const cycle = done.map((c) => c.finished - c.started + 1);
console.log('cycle times in days:', cycle.join(', '));
console.log('average:', (cycle.reduce((a, b) => a + b, 0) / cycle.length).toFixed(1), 'days');in progress: 4 of 3 OVER LIMIT, finish something first in review: 1 of 2 cycle times in days: 3, 4, 6 average: 4.3 days
What this code does
Each column with a limit is counted, and a column over its limit is reported with the Kanban response: finish something before starting more. Cycle time is the number of working days from start to finish, counting both ends, so a card started and finished on the same day takes one day. The average cycle time is a simple health measure: if it creeps up, cards are getting stuck.
The over-limit warning in that example happened on the second Thursday of Sprint 1, when Odalys started a fourth card while waiting for a review. Mira did not scold anyone; she reviewed the waiting pull request herself, and the next morning's stand-up added a rule that reviews come before new work.
Definition of Ready and Definition of Done
Two short checklists stop most arguments before they start. The Definition of Ready says what a story needs before it can enter a sprint: a reason, acceptance criteria as examples, a size, and no unknown that would block it. The Definition of Done says what every change must have before it counts as finished. The team writes its Definition of Done on the first day and pins it in the repository, and every pull request template repeats it as a checklist.
| Definition of Done item | Why |
|---|---|
| Acceptance examples pass as automated tests | The story does what was agreed, and keeps doing it |
| Unit tests for new rules; coverage does not drop | Rules such as claiming are where bugs hurt |
| Lint, type check and formatting pass in CI | Reviews spend time on design, not commas |
| Reviewed and approved by one other person; Theo for migrations | A second pair of eyes; the database owner sees schema changes |
| Keyboard and screen reader check for any new screen | Accessibility is part of done, not a later phase |
| No secrets, no real personal data, no console logging of request bodies | WEB-230 rules |
| Deployed to staging by the pipeline and checked there | Done means usable, not merged |
| User-facing text checked with Lucy or Rosa | Labels in the users' words |
Branches, commits and pull requests
The studio uses trunk-based development with short-lived branches, the workflow set up in JS-210. The main branch is always releasable. Each story is built on a branch named after its card, such as rr-14-claim-rules, that lives for a day or two, and is merged through a pull request once CI passes and a reviewer approves. Long-lived branches are avoided, because the longer a branch lives, the more painful merging it becomes. A feature that is not ready for users can still be merged early behind a feature flag, the technique JS-260 used for the board layout.
Commit messages follow Conventional Commits, also from JS-260, because the release script uses them to choose the next version number and write the changelog. A message starts with a type, an optional scope in parentheses, and a short summary: *feat(claims): refuse overlapping runs*, *fix(offers): keep the photo when editing*, *docs(adr): supersede ADR 0004*. An exclamation mark after the type, or a footer starting BREAKING CHANGE, marks a change that breaks an existing interface.
// Validate commit messages against the Conventional Commits pattern the release script needs.
const types = ['feat', 'fix', 'docs', 'test', 'refactor', 'chore', 'ci', 'perf'];
const re = new RegExp(`^(${types.join('|')})(\\([a-z-]+\\))?(!)?: [a-z].{2,71}$`);
const messages = [
'feat(claims): refuse overlapping runs',
'fix: keep the photo when an offer is edited',
'Feature: driver list',
'feat(api)!: rename window to pickup_window',
'chore(deps): Bump express',
];
for (const m of messages) {
const match = m.match(re);
const kind = !match ? 'REJECT' : match[3] ? 'breaking' : match[1] === 'feat' ? 'minor' : match[1] === 'fix' ? 'patch' : 'none';
console.log(`${kind.padEnd(8)} ${m}`);
}minor feat(claims): refuse overlapping runs patch fix: keep the photo when an offer is edited REJECT Feature: driver list breaking feat(api)!: rename window to pickup_window REJECT chore(deps): Bump express
What this code does
The regular expression is built from the list of allowed types, with an optional scope in parentheses and an optional exclamation mark for breaking changes. The summary must start with a lower-case letter and be between 3 and 72 characters long, which keeps changelogs tidy. Each accepted message is also classified by the version bump it would cause, which is what the release script does with it.
Code review is where the two apprentices learn most, and Gareth gives the team three rules for it. Review the change, not the person: comments say what the code does and what would be better, never who should have known. Keep pull requests small, ideally under 400 changed lines, because large ones get rubber-stamped. And respond to reviews within half a day, because a waiting pull request is work in progress that nobody can move. A CODEOWNERS file makes Theo a required reviewer for anything in the migrations folder and Sana for the shared component styles.
# Branch protection kept as code, applied by the repository settings app
branches:
main:
protection:
required_status_checks:
strict: true
contexts: [quality, test, e2e, rescue-runs-build]
required_pull_request_reviews:
required_approving_review_count: 1
require_code_owner_reviews: true
dismiss_stale_reviews: true
enforce_admins: true
allow_force_pushes: falseWhat this code does
The settings require four CI checks to pass on an up-to-date branch before anything merges into main. One approving review is needed, code owners must approve changes to the files they own, and a new push dismisses old approvals so that reviewers always see the final version. Force pushes are refused and the rules apply to administrators too, so nobody can bypass them by accident.
Risks and communication
The last planning artefact is a risk register: a short list of things that could go wrong, how likely and how harmful each is, and what the team will do about it. The top risks in April are Theo's token endpoint arriving late, donors not using the app because a phone call is easier, the two apprentices getting stuck without asking for help, and the cold-food rule being implemented wrongly. Each has an owner and a response. For the donor risk, the response is to recruit two donors, Copperleaf Bakery and Pine Hill Grocers, to try every weekly build.
Communication with the client is simple and regular. Every Tuesday at 2:00 p.m. the team shows Lucy and Rosa what works that week, for twenty minutes, on staging, with invented data. Paul gets a five-line e-mail every second Friday: what was finished, what is next, what is at risk, what decision is needed from him, and whether the dates still hold. Nobody is ever surprised by a slip, because slips are reported the week they are noticed.
Worked problem
Re-planning after Sprint 1
The team planned 18 points for Sprint 1 and finished 15. Sprint 2 will have one fewer person-day because Tavish has a college exam. Using the same focus factor of 0.6 and 0.75 days per point as a check, and the measured velocity as the main guide, how many points should Sprint 2 plan?
Show solution
- Measured velocity: 15 points in Sprint 1.
- Availability check: person-days 22 − 1 = 21; focused days 21 × 0.6 = 12.6; points 12.6 ÷ 0.75 = 16.8, about 17.
- The availability estimate was already too high once (18 planned, 15 done), so the team trusts the measurement more.
- Plan about 15 to 16 points, and keep one could-have ready in case the sprint goes well.
Answer: The team plans 16 points for Sprint 2: slightly above the measured 15 because Sprint 1 included the one-off token delay, but well below the 17 the availability formula suggests. The plan is adjusted again after Sprint 2.
Common mistakes
MistakeEstimating stories in hours.
InsteadSize stories relative to a reference story in points, and measure velocity.
MistakeLetting the first person to speak set the estimate.
InsteadUse planning poker: reveal together, then discuss the extremes.
MistakeStarting new work while reviews wait.
InsteadSet WIP limits and finish or review before starting something new.
MistakeCalling a story done when it is merged.
InsteadUse a Definition of Done that includes tests, review, accessibility checks and staging.
MistakeKeeping slips quiet until the deadline.
InsteadReport risks and slips in the week they are noticed, with a decision request if needed.
Summary and key terms
- Process should be the smallest amount that lets a team see problems early.
- From Scrum the team takes two-week sprints with planning, reviews, retrospectives and short stand-ups; from Kanban a visible board with WIP limits.
- Stories are sized relatively in points with planning poker, and capacity is estimated from availability and a focus factor, then corrected using measured velocity.
- A Definition of Ready and a Definition of Done remove arguments about when work starts and finishes.
- Trunk-based development with short branches, feature flags, Conventional Commits, small pull requests, prompt reviews, code owners and branch protection keep the main branch releasable.
- A risk register and regular, short communication with the client prevent surprises.
- Sprint
- A fixed period, here two weeks, ending with working software and a review.
- Story point
- A relative measure of a story's size compared with a reference story.
- Planning poker
- An estimation technique where everyone reveals a size at once and the extremes explain their reasoning.
- Velocity
- The number of story points a team actually finishes in a sprint.
- Focus factor
- The share of available time actually spent on sprint stories.
- Work-in-progress limit
- The most cards allowed in a board column at once.
- Cycle time
- The time from starting a piece of work to finishing it.
- Definition of Done
- The checklist every change must meet before it counts as finished.
- Trunk-based development
- A workflow where everyone merges small changes into one main branch often.
- Risk register
- A list of possible problems with their likelihood, impact, owner and response.
Practice problems
Work each problem on paper first, then reveal the answer to check.
Why use relative story points rather than hours?
Show answer
People compare sizes better than they estimate absolute time, and velocity turns points into plans.
What should a person do when the In progress column is full?
Show answer
Help finish or review existing work instead of starting something new.
Why does the Definition of Done include deployment to staging?
Show answer
Done means usable by someone, not merely merged.
What does an exclamation mark after the type in a Conventional Commit mean?
Show answer
The change breaks an existing interface, so the release is a major version.
Try it yourself
Commit message check
Complete bump(message). It returns major, minor, patch, none or invalid.
Valid messages look like type(scope)!: summary where the scope and ! are optional and the type is one of feat, fix, docs, test, chore. ! means major; otherwise feat is minor, fix is patch, and the rest are none.
function bump(message) {
return 'none';
}
for (const m of ['feat(claims): refuse overlaps', 'fix: photo lost on edit', 'docs(adr)!: new format', 'chore: tidy', 'Added stuff']) {
console.log(bump(m));
}Try it yourself
Sprint capacity
Complete capacity(days, focus, daysPerPoint). days is an object of person-days for each team member.
Return the points the team can plan: total person-days times focus, divided by daysPerPoint, rounded down to a whole number.
function capacity(days, focus, daysPerPoint) {
return 0;
}
console.log(capacity({ Mira: 8, Odalys: 7, Tavish: 7 }, 0.6, 0.75));
console.log(capacity({ Mira: 8, Odalys: 7, Tavish: 6 }, 0.6, 0.75));
console.log(capacity({ Mira: 5 }, 0.5, 1));Lesson quiz · 5 questions
Score 60% or more to complete this lesson.
Create a free account to save your progress, take quizzes and earn a certificate.