Agentic SDLC — Planning & Requirements Map
Agentic SDLC — Planning & Requirements Map
PLANNING & REQUIREMENTS How a vague idea becomes something an agent can build, and prove it built. Agentic SDLC · Workshop 1 + the Project Manager, Requirements Reviewer and Value Chain Expert agents ↖ Agentic SDLC meta-map 1 BRAIN DUMP the quarry every idea, out of your head the book club: "we keep arguing about the next book" 2 REQUIREMENTS the blueprint testable: REQ-001… the book club: REQ-003: one ranked ballot per member per open round 3 REVIEW the inspector a fresh agent breaks the spec the book club: ⚠ tie-break unstated · ⚠ double vote? 4 VALUE the scales Kano · RICE · 2×2 the book club: Voting = BASIC → Phase 1 5 ROADMAP the railway phases · deps · batches the book club: Batch 3, after accounts + rounds 6 SPEC the logbook context + definition of done the book club: spec delta + issue: 5 boxes = done gaps found → revise new ideas found while building go back into the dump: it's iterative, not final ▼ the six stages below, in this order (snake: top row → then bottom row right-to-left) ▼
STAGE 1 · GET IT ALL OUT Brain dump metaphor: the quarry Dig everything out first, sort it second. An agent can only plan around ideas it has seen. 1 Dump, don't organise Talk. Let the agent ask you questions. Sort nothing yet. You know the summary of your project, not the details. The details are what become requirements, and they only come out when you talk past the summary. Use voice input if you can. Tell the agent to ask follow-up questions and to capture the out-of-scope stuff too. Out-of-scope ideas are not waste: they become the backlog, and writing them down is what lets you stop thinking about them. 1 of 3 YOU ARE HERE · Plan › Brain dump › Dump
your head vote on books reminders? discussion Goodreads host role AI picks? progress bar ▸ Worked example: the book club's raw dump zoom in PROMPT (Workshop 1, step 1) I'm going to brain dump everything I want in my project. Don't organize it yet, just help me get it all out. Ask me follow-up questions to pull out more ideas. I want to capture EVERYTHING, even stuff that's probably out of scope. WHAT CAME OUT (illustrative) we keep arguing about the next book / some kind of vote? / the host should be able to open and close voting / reminders before the meeting / a place to talk about chapters / import our shelves from Goodreads / maybe an AI that suggests books / a progress bar so people admit they didn't finish AGENT FOLLOW-UPS THAT FOUND DETAIL Who can vote, only members? · One book each, or ranked? · What happens on a tie? · Does the host vote? Notice: the tie question surfaced here, in the dump. It comes back in stage 3. 2 Four shapes of one idea Feature → user story → requirement → acceptance criteria. Each step is more testable. A feature is a name ("voting"). A user story says who wants it and why: "As a ___, I want ___, so that ___". The why is what helps an agent make good calls you didn't spell out. A requirement is one precise, testable statement: "The system shall…", numbered REQ-001, REQ-002. Acceptance criteria are the checks that say it's done. You won't write most of these yourself. Claude drafts them and you review them, so you need to recognise each shape. 2 of 3 YOU ARE HERE · Plan › Brain dump › Four shapes
FEATURE a name USER STORY who + why REQUIREMENT testable statement ACCEPTANCE the checks for done more testable
▸ Worked example: one idea, four shapes zoom in FEATURE Voting on the next book USER STORY As a book club member, I want to vote on the next book, so that the pick reflects the group, not the loudest person. REQUIREMENT REQ-003: The system shall let each member cast one ranked ballot per round while the host has the round open. ACCEPTANCE CRITERIA ✓ member votes in an open round → ballot saved, confirmation shown ✓ round is closed → vote button disabled, "voting closed" shown ✓ non-member tries to vote → refused The "so that" clause is why the agent won't build a host-only poll. 3 Defer, don't forget Agents unblock years of ideas at once. The roadmap is where they wait. When agents suddenly make building cheap, every idea you've shelved comes back at once. Liz calls this "task diarrhea". The cure isn't to forget the ideas. Write them all down, then send most of them to a later phase or the backlog. Start one project. Finish Phase 1 before you add features. The agents keep working while you sleep, so you don't have to watch them. If you have ADHD, give each agent role its own terminal (and a colour) so the terminal holds the context instead of your head. 3 of 3 YOU ARE HERE · Plan › Brain dump › Defer
every idea, all at once PHASE 1 BACKLOG now, one project kept, not lost
▸ Signs you're in it, and the healthy pattern zoom in SIGNS (Workshop 1) ✗ haven't eaten in 6 hours ✗ skipped plans to code ✗ started 3 projects before finishing 1 ✗ can't stop thinking about "just one more feature" ✗ coding at 2am "because I'm almost done" HEALTHY ✓ start one project ✓ complete Phase 1 before adding features ✓ set work hours and stop ✓ use the roadmap to DEFER ideas (not forget them) ✓ this capability isn't going away BEFORE YOU START Tell your people you're about to learn fast software development and might get hyperfocused. Decide your work hours in advance. Claude Code works on a phone, so you don't have to sit at your computer. BENCH · TRY IT ON YOUR AGENT Which shape is this? "As a member, I want a reminder the day before we meet, so that I actually finish the book."
A feature A user story A requirement Acceptance criteria Pick one. Every answer explains itself — wrong ones teach the most.
▶ Now yours: take one line from your own brain dump and write it in all four shapes.
YOU ARE HERE · Plan › Brain dump › Bench
STAGE 2 · MAKE IT TESTABLE Requirements metaphor: the blueprint If you can't say "yes, this is done" or "no, it isn't", you've written a feeling, not a requirement. 1 Anatomy of a requirement Five parts: who, does what, when, within what limits, and how we check it. Every solid requirement has five parts, though some can be implicit. ACTOR: who or what acts ("the system", "an admin"). ACTION: the specific behaviour. TRIGGER: when it happens. CONSTRAINT: the limits ("within 200ms", "with bcrypt"). ACCEPTANCE: how we'll know it's done. Missing parts are where an agent guesses. Leave out the method on "user authentication" and the agent might build OAuth when you wanted email and password. 1 of 3 YOU ARE HERE · Plan › Requirements › Anatomy
ACTOR the system ACTION locks the account TRIGGER after 5 failed logins CONSTRAINT for 15 minutes ACCEPTANCE verified by E2E test
▸ Bad → better → best (Workshop 1) zoom in BAD User authentication — how? what triggers it? what security standard? BETTER The system shall authenticate users via email/password. — no success/failure behaviour BEST REQ-001: The system shall authenticate users via email/password with bcrypt hashing (cost factor 12). - valid credentials → session token generated, redirected to dashboard - invalid credentials → error message shown, no redirect - password stored as bcrypt hash, never plaintext - after 5 failed attempts, account locked for 15 minutes - session tokens expire after 24 hours Verified by: unit tests (token / 401), DB inspection (hashes), E2E lockout test 2 You can't make it "good" Swap feelings for numbers: "fast" becomes "p95 under 200ms". "You will should yourself to death in software. There's infinity shoulds." You can make a thing redder, faster or more polished, but you can't make it "good": that's a feeling, and an agent will read it however it likes. Turn each should into a measurable statement, or cut it. Watch the four kinds as well: FUNCTIONAL (what it does), NON-FUNCTIONAL (how well: speed, uptime, privacy), INTERFACE (how it talks to other systems), DATA (what it stores and for how long). 2 of 3 YOU ARE HERE · Plan › Requirements › Not 'good'
"should be fast" a feeling p95 < 200ms a measurement how to check it: 200ms
▸ Measuring "p95 < 200ms" in plain words zoom in Run 100 requests. Sort them by response time. Look at the 95th one. Under 200ms → done. Over → not done. Nobody has to decide whether it "feels fast". FOUR KINDS, ONE LINE EACH (Workshop 1) FUNCTIONAL The system shall export data to CSV format. NON-FUNCTIONAL The system shall handle 1000 concurrent users. INTERFACE The system shall integrate with Stripe for payment processing. DATA The system shall support up to 10MB file uploads per transaction. Beginners skip non-functional requirements most often, and they're the ones a reviewer catches. 3 Edges & right size Write the failure cases now, or the agent builds only the happy path. Agents build exactly what you describe. Describe only the happy path and you get only the happy path, then you spend your week on "what if the file is 50MB?". Put the failure modes in the acceptance criteria. Size matters too. "User management" is too broad: create? delete? roles? "A blue button at (100,200) in Arial 14" is too narrow, because you're doing the agent's job. Aim for the right size: one focused piece of work that fits in a single reviewable pull request. 3 of 3 YOU ARE HERE · Plan › Requirements › Edges
just right too broad: "user management" too narrow: pixel coordinates 50MB file .exe file upload fails no picture yet ▸ REQ-015 with its edge cases (Workshop 1) zoom in REQ-015: Profile Picture Upload The system shall allow users to upload profile pictures. Acceptance Criteria: - Supported formats: JPEG, PNG, GIF - Max file size: 5MB - Automatic resize to 400x400px, maintain aspect ratio - If file too large → error message with size limit - If unsupported format → error message with supported formats - If upload fails → show error, preserve old picture - If no picture uploaded → show default avatar Without the last five lines, the agent ships the happy path and you find the rest in production. BENCH · TRY IT ON YOUR AGENT Which one could an agent prove it finished? Four lines from a real first-draft requirements file. Pick the one that's already a good requirement.
REQ-005: Good error handling REQ-006: Use React for the frontend REQ-007: The system shall complete checkout in ≤3 clicks from the cart REQ-008: The system shall authenticate users, manage sessions and handle password resets Pick one. Every answer explains itself — wrong ones teach the most.
▶ Now yours: find the vaguest line in your requirements.md and give it a number someone could measure.
YOU ARE HERE · Plan › Requirements › Bench
STAGE 3 · BREAK THE SPEC FIRST Adversarial review metaphor: the inspector A second agent tries to break the spec before the code does. Bugs are cheapest to fix while they're still sentences. 1 Writer ≠ reviewer The agent that wrote the spec can't see its own gaps. Use a fresh one. An agent that just wrote a document is primed by its own reasoning. It reads what it meant, not what it wrote. So the review is a separate agent with a fresh context, a rubric, and an adversarial brief: "find what would make an agent build the wrong thing". It returns gaps, you or the author revise, and you loop until nothing blocking is left. Then it's ready for agents. The Requirements Reviewer agent in this course does this job. 1 of 3 YOU ARE HERE · Plan › Review › Loop
DRAFT requirements.md REVIEWER fresh context + rubric GAPS what would go wrong READY for agents revise no blockers
▸ What a review actually returns zoom in Requirements Reviewer (from the agent's own example) ✓ Introduction: clear project purpose ✓ User Stories: 3 stories covering login, registration, password reset ⚠ Non-Functional Requirements: Missing - No password complexity requirements stated - No session timeout specified - No rate limiting defined ⚠ Testing Requirements: Incomplete - No acceptance criteria for 'remember me' feature - Edge case not covered: what happens if email service is down? Every ⚠ is a decision the coding agent would otherwise have made silently. 2 The 14-point rubric A checklist turns "looks fine" into "section 5 is empty". Ask a reviewer "is this good?" and you get compliments. Hand it a rubric and you get a gap list. The Requirements Reviewer checks 14 sections. Beginners usually leave the same ones empty: non-functional requirements, testing, deployment (including how to roll back), maintenance, and risks & assumptions. Two sections are optional for small projects. You don't need all 14 for a weekend app, but you should decide on purpose which ones to skip. 2 of 3 YOU ARE HERE · Plan › Review › Rubric
1. Introduction 2. System goals 3. User stories 4. Functional 5. Non-functional 6. Technical spec 7. Design 8. Testing 9. Deployment 10. Maintenance 11. Milestones* 12. Budget* 13. Risks & assumptions 14. Appendices red = often left empty · * optional
▸ What the weak sections catch: book club zoom in 5 NON-FUNCTIONAL Is the ballot secret? Can the host see who voted for what? 8 TESTING There are no acceptance criteria for a tie. What does the result screen show? 9 DEPLOYMENT If a release breaks voting mid-round, how do we roll back, and do ballots survive? 10 MAINTENANCE Who notices when the reminder emails stop sending? 13 RISKS & ASSUMPTIONS We assumed every member has an email address. One doesn't. None of these show up in a demo. All of them show up in week two. 3 Stamps of rejection Four anti-patterns to reject on sight, plus a naming trap. 1. SOLUTION IN DISGUISE: "use React" isn't a need. 2. VAGUE QUALIFIER: "user-friendly" means nothing to an agent. 3. SEVERAL IN ONE: you can't track a requirement that's partly done. 4. NO ACCEPTANCE CRITERIA: the agent marks it done and you can't check. One more from Liz's experience: name the planning agent a Project Manager, Business Analyst or Value Chain Expert, not a "Product Manager". In her experience that name gives worse roadmaps, and she says she doesn't know why. 3 of 3 YOU ARE HERE · Plan › Review › Anti-patterns
SOLUTION IN DISGUISE VAGUE QUALIFIER SEVERAL IN ONE NO ACCEPTANCE ▸ Inspector's report on the book club's REQ-003 zoom in REQ-003: The system shall let each member cast one ranked ballot per round while the host has the round open. FOUND ⚠ Tie-break rule unstated. Two books with equal points: who wins? ⚠ "Ranked" is undefined. Rank all candidates, or a top 3? ⚠ Voting twice: does the second ballot replace the first or get rejected? ⚠ The host never closes the round: does it stay open forever? ⚠ Non-functional: is the ballot secret from the host? FIXED + Members rank their top 3. Ties are broken by most first-choice votes, then by the host. + A second ballot replaces the first while the round is open. The round closes itself at meeting time. BENCH · TRY IT ON YOUR AGENT Your review came back: "Looks great! 👍" You asked an agent to review your requirements.md. That's the whole reply. What next?
Good. Start the coding agents. Ask the same agent that wrote it to double-check. Fresh agent, the 14-point rubric, and: "list the 3 weakest sections and what an agent would build wrong because of each" Read it yourself line by line instead. Pick one. Every answer explains itself — wrong ones teach the most.
▶ Now yours: run the Requirements Reviewer on your requirements.md. Which section number came back weakest?
YOU ARE HERE · Plan › Review › Bench
STAGE 4 · WEIGH IT Value & priority metaphor: the scales Everything on the list should exist eventually. The scale decides what exists first. 1 What job is it hired for? Jobs To Be Done + Kano: is it expected, better-is-better, or a delight? The Value Chain Expert agent starts by asking what job the user is hiring this feature to do. Then it sorts the feature with the Kano model. BASIC: users expect it, and they notice when it's missing. PERFORMANCE: more is better (faster, bigger). DELIGHTER: unexpected, and creates a wow. Basics come first, because a delighter on top of a missing basic doesn't delight anyone. Ask for this analysis by name, since the agent knows these frameworks. 1 of 3 YOU ARE HERE · Plan › Value › Kano
BASIC vote, see result PERFORMANCE reminders, threads DELIGHTER AI suggestions missing → angry more → happier present → wow build left to right
▸ The agent's own worked example: PDF export zoom in Value Chain Expert, "Evaluate: Add export to PDF for reports" Job To Be Done: "When presenting to executives, users need professional-looking reports they can share offline" Kano Category: Basic Expectation (users expect export in reporting tools) VRIO: Valuable ✓ Rare ✗ (all competitors have it) → Competitive Parity Recommendation: table stakes, so lacking it hurts more than having it helps. BOOK CLUB Job: "When we can't agree, we need a fair pick so the meeting isn't an argument." Voting = BASIC (it's the whole app). Reminders = PERFORMANCE. AI suggestions = DELIGHTER. 2 RICE: a number to argue with (Reach × Impact × Confidence) ÷ Effort. The score is less useful than the argument it forces. RICE turns "I feel like this matters" into four separate guesses you can challenge one at a time. REACH: how many people it touches. IMPACT: how much it helps each of them (0.25 to 3). CONFIDENCE: how sure you are (0–100%). EFFORT: how big it is, relative to everything else on the list. The number won't be precise. Its use is that when two people disagree, you can see which of the four guesses they disagree on. 2 of 3 YOU ARE HERE · Plan › Value › RICE
R Reach × I Impact × C Confidence E Effort
▸ Two features, two scores zoom in PDF EXPORT Reach 1000 × Impact 0.25 × Confidence 0.9 ÷ Effort 0.5 = 450 REAL-TIME COLLABORATION Reach 500 × Impact 2 × Confidence 0.7 ÷ Effort 3 = 233 READ IT Collaboration helps each user far more (2 vs 0.25), but it's six times the effort and less certain. PDF export wins first because it's small and sure, not because it matters more. The agent's comparison still calls collaboration the competitive ADVANTAGE, so it goes in the plan, later. Effort here is relative size. Compare items against each other; don't treat it as a promise. 3 Value × complexity → phase The 2×2 that turns scores into a roadmap. The Business Value Analyst prompt from Workshop 1 scores every requirement 1–10 for value and 1–10 for complexity, then sorts it. High value and low complexity: Phase 1. High value and high complexity: Phase 2, done carefully. Low value and low complexity: Phase 3, if you get to it. Low value and high complexity: the backlog, maybe never. Don't front-load the hard things. Put a simple working version in Phase 1 and improve it later, so you have working software early. 3 of 3 YOU ARE HERE · Plan › Value › Matrix
value ↑ complexity → PHASE 1 do first PHASE 2 do carefully PHASE 3 if time BACKLOG maybe never vote results reminders threads Goodreads AI picks
▸ The prompt that fills the matrix zoom in You are a Business Value Analyst helping prioritize features for an MVP. Review the requirements.md file and create a priorities.md file that includes: 1. Business Value Score (1-10) for each requirement 2. Implementation Complexity (1-10) 3. Risk Assessment — what could go wrong? blast radius if it fails? 4. Priority Matrix - High value + low complexity = Phase 1 (do first) - High value + high complexity = Phase 2 (do carefully) - Low value + low complexity = Phase 3 (do if time) - Low value + high complexity = Backlog (maybe never) Save this as priorities.md BENCH · TRY IT ON YOUR AGENT Where does the AI book recommender go? The book club app can't run a vote yet. A member is excited about an AI that suggests the next book. Where does it go?
Phase 1, since it's the exciting part Phase 2, right after voting works Phase 3 or backlog, written down with its reason Don't write it down; it's scope creep Pick one. Every answer explains itself — wrong ones teach the most.
▶ Now yours: put your three most exciting ideas on the 2×2. How many are actually Phase 1?
YOU ARE HERE · Plan › Value › Bench
STAGE 5 · ORDER + PARALLEL Roadmap metaphor: the railway Dependencies decide the order. Batches decide what runs at the same time. The Project Manager agent keeps the timetable. 1 Fast waterfall Plan the whole phase, build it in parallel, review the phase. Then do the next one. Traditional Agile plans one small slice at a time because each slice used to be expensive to build. With agents, building is cheap and unclear requirements are expensive. So the course uses "fast waterfall": define a whole phase up front (quickly), build its pieces in parallel, review the phase, then plan the next. Phase 1 is the MVP, the minimum that works. Phase 2 is what users expect. Phase 3 is polish. Liz's framing: "build the factory, not the thing." Your requirements and prompts are the factory, and the code is what it produces. 1 of 3 YOU ARE HERE · Plan › Roadmap › Phases
PHASE 1 MVP PHASE 2 launch PHASE 3 polish BACKLOG later each step: plan it all → build in parallel → review
▸ The book club's roadmap.md zoom in PHASE 1 — MVP (nothing works without these) REQ-001 Member accounts + invite link REQ-002 Host opens/closes a round REQ-003 Ranked ballot (top 3) REQ-004 Results with tie-break Success: a real club picks a real book with it. PHASE 2 — what members expect [depends on Phase 1] REQ-010 Reminder before the meeting REQ-011 Chapter discussion threads PHASE 3 — polish [depends on Phase 2] REQ-020 Goodreads shelf import REQ-021 Reading progress bar BACKLOG AI book suggestions (see stage 4 bench) 2 Dependencies → batches Draw what blocks what. Everything in a batch can run in parallel. You can't build "reset password" before "login" exists. Mark each requirement's dependencies ([depends on REQ-001]), and the graph sorts itself into batches. Every requirement in a batch has its dependencies done, so one agent per requirement can run at the same time. Before you start parallel agents, define the interfaces: API contracts, function signatures, data schemas. Otherwise two agents each guess the other's half and the merge fails. 2 of 3 YOU ARE HERE · Plan › Roadmap › Dependencies
BATCH 1 REQ-001 register BATCH 2 REQ-002 verify email REQ-003 login BATCH 3 REQ-004 reset pw ▸ Dependencies written down (Workshop 1) zoom in REQ-001: User Registration REQ-002: Email Verification [depends on REQ-001] REQ-003: Login [depends on REQ-001] REQ-004: Password Reset [depends on REQ-001, REQ-002] WHY IT MATTERS Once REQ-001 is in, REQ-002 and REQ-003 can run as two agents at once. REQ-004 waits for both. INTERFACE FIRST (Mistake 7) Before batch 2 starts, write down the contract both agents share, for example: POST /auth/login {email, password} → 200 {token} | 401 {error} users table: id, email, password_hash, verified_at Without it, each agent invents its own version and the merge breaks. 3 The Project Manager agent Plan → dispatch → track → archive. Your discipline system. The Project Manager agent turns specs into a roadmap of single-PR-sized phases grouped into parallel batches. It hands each worker agent a dispatch packet: goal, tasks, the files it will touch, constraints, and concrete completion criteria. It updates checkboxes, flags blockers, and spots work that's newly unblocked. It also moves finished work to an archive so the live roadmap stays short. As the human, watch the roadmap, not every line of code. In Liz's words: "I, as the CTO, mostly just care about the roadmap." 3 of 3 YOU ARE HERE · Plan › Roadmap › Project Manager
PLAN DISPATCH TRACK ARCHIVE not started in progress complete blocked
▸ plans/roadmap.md, live (Project Manager format) zoom in ## Batch 1: Foundation ⚪ REQ-001: Database schema setup Tasks: [ ] users table [ ] projects table [ ] migrations Files: src/db/schema.sql, migrations/ Effort: S Completion: All tables created, migrations tested 🟡 REQ-002: User model implementation Agent: Roy Tasks: [x] Define User class [ ] validation [ ] unit tests ## Batch 2: Authentication (Depends: REQ-001, REQ-002) 🔴 REQ-004: Password reset flow Blocked by: Email service (external dependency) Sizes are S or M only. Anything bigger gets broken down before it's dispatched. BENCH · TRY IT ON YOUR AGENT REQ-001 just merged. What can start now? Graph: 002 and 003 depend on 001. 004 depends on 001 and 002. You have three idle agents.
REQ-004, since it's the biggest REQ-002 and REQ-003 in parallel, after agreeing the users-table contract Only REQ-002, one at a time to be safe All three, they'll figure it out Pick one. Every answer explains itself — wrong ones teach the most.
▶ Now yours: mark [depends on …] on every requirement in your roadmap. What's in your batch 1?
YOU ARE HERE · Plan › Roadmap › Bench
STAGE 6 · WHAT THE AGENT READS Spec = context metaphor: the logbook The conversation gets deleted. The spec stays. Every agent session starts by reading it. 1 Why the plan is the context Agents start blank. Whatever isn't in a file doesn't exist for them. "Anytime you have a conversation with Claude, imagine it's going to get deleted. Because it will." Each new session, and each parallel worker, starts with no memory of your chat. It knows only what it reads: the repo, CLAUDE.md, the roadmap, the proposal it was given. That's why every step on this map writes a file (requirements.md, priorities.md, roadmap.md). The plan is how you hand your intent to an agent that wasn't in the room. 1 of 3 YOU ARE HERE · Plan › Spec › Context
SPEC in the repo session 1 session 2 worker B chat evaporates
▸ Dispatch packet: what the REQ-003 worker reads zoom in GOAL Members can cast a ranked top-3 ballot in an open round. TASKS [ ] ballots table [ ] POST /rounds/:id/ballot [ ] ballot form [ ] tests per criterion FILES src/models/ballot.py, src/api/rounds.py, web/BallotForm.tsx, tests/test_ballot.py CONSTRAINTS Ballot is secret from the host. Don't touch auth (REQ-001 owns it). Contract: openspec/changes/add-book-voting/design.md DONE WHEN Every scenario in specs/voting/spec.md has a passing test, including: voting twice, closed round, non-member, tie. Everything the inspector found in stage 3 is now in the packet. The worker can't miss it. 2 OpenSpec: specs that live in the repo specs/ is the truth. changes/ holds proposals. Draft → review → implement → archive. OpenSpec is an open-source CLI for spec-driven development, and it works with Claude Code, Cursor and other assistants. openspec/specs/ holds the current truth about the system. openspec/changes/ holds proposals. Each change is a folder: proposal.md (why), tasks.md (the checklist), design.md (technical decisions), and spec deltas marked ADDED / MODIFIED / REMOVED. When it ships, the change is archived and its deltas merge into specs/. Already have a codebase? Ask Claude: "Can you onboard this repository into OpenSpec?" 2 of 3 YOU ARE HERE · Plan › Spec › OpenSpec
openspec/ └ specs/ └ voting/spec.md └ changes/ └ add-book-voting/ └ proposal.md └ tasks.md └ design.md └ specs/voting/spec.md Δ DRAFT REVIEW IMPLEMENT ARCHIVE
▸ Spec delta: changes/add-book-voting/ zoom in ## ADDED Requirements ### Requirement: Ranked ballot Each member SHALL rank up to 3 candidate books while the round is open. #### Scenario: member votes twice - WHEN a member submits a second ballot in an open round - THEN the second ballot replaces the first #### Scenario: round closed - WHEN a member opens a closed round - THEN the vote form is disabled and "voting closed" is shown #### Scenario: tie - WHEN two books have equal points THEN most first-choice votes wins; if still tied, the host decides Each Scenario is an acceptance criterion an agent can turn directly into a test. 3 What "done" means Done = every acceptance criterion is verified. Not "the agent said so". Without acceptance criteria, "done" is a matter of opinion, and an agent will happily say "all done!". With them, done is checkable. Each criterion becomes a test. The tests run in CI. The issue or pull request links back to the requirement number. Then a reviewer, human or agent, checks the evidence: test names matching the criteria, a screenshot of the failure case, not just the happy path. This is the last step of planning and the first step of shipping. The other maps pick it up from here. 3 of 3 YOU ARE HERE · Plan › Spec › Done
criterion test CI green evidence ☑ votes twice → replaces ☑ closed round → disabled ☑ non-member → refused ☐ tie → first-choice rule 3 of 4: NOT done
▸ The GitHub issue an agent works from zoom in Title: REQ-003 Ranked ballot (top 3) Labels: phase-1, batch-3 Spec: openspec/changes/add-book-voting/ Acceptance criteria - [ ] Member votes in an open round → ballot saved, confirmation shown - [ ] Second ballot in an open round replaces the first - [ ] Closed round → form disabled, "voting closed" - [ ] Non-member → 403 - [ ] Tie → most first-choice votes wins, then host decides Verified by: one test per box (named after it) + screenshot of the closed-round state The PR is mergeable when every box is checked AND has evidence. That's the definition of done. BENCH · TRY IT ON YOUR AGENT The agent says: "REQ-003 is done ✅" Which evidence would actually let you close the issue?
Its message saying it's done and everything works The code compiles and the app starts One passing test per acceptance criterion, named after it, including the tie and closed-round cases A screenshot of a successful vote Pick one. Every answer explains itself — wrong ones teach the most.
▶ Now yours: open one of your issues. Could a stranger tell from it alone when the work is done?
YOU ARE HERE · Plan › Spec › Bench
Brain dump THE QUARRY Requirements THE BLUEPRINT Adversarial review THE INSPECTOR Value & priority THE SCALES Roadmap THE RAILWAY Spec = context THE LOGBOOK
←
0 / 0
→
Explore
Click anything to zoom into it · scroll to zoom · drag to panEsc zoom out one level · Home whole atlas1 –4 jump to a quadrant · / search
Tour
→ / space next stop · ← previousTeach
N presenter notes for whatever you're looking at · F fullscreenReading the map
The whole atlas is one safety case. The top goal is “this agent is fit to deploy”;
each quadrant is one leg of the argument; each district is a family of tools for that leg.
Small text appears as you zoom in. Some tiles have controls you can click.
Click anything to zoom in · scroll to zoom · Esc to back out · → for the guided tour