PlumbA developer's workflow
What a developer does, from picking up work to closing it. This is the corpus's main flow: every other chapter expands one of its steps, and its file name says which. This is framed as an agile process, but plumb does not require any specific methodology.
dev00 I want to close a story Nothing holds it
As a developer I want to finish a piece of work and have it shown to be finished, so that what I hand over is complete rather than asserted.
Requirements (8)
- dev00-ur1a story carries an identifier the team already uses
- dev00-ur2the team records somewhere what is in flight
- dev00-ur3the team has somewhere to ask what a story means
- dev00-sr1a version control system with branches and pull requests
- dev00-sr2a test runner the language supports
- dev00-sr3plumb set up for the project (dev00-1), with its adapter for that language
- dev00-nfr1running plumb costs about what running the tests already costs
- dev00-nfr2nothing in the flow writes a status anybody could have typed
dev00-1 bring plumb to a project Nothing holds it
As a team I want plumb installed and pointed at our project without reading its repository, so that the first thing we see is a board answering for the stories our tests cite.
Requirements (0)
dev01 take a story from the sprint backlog Nothing holds it
As a developer starting work I want to take the next thing the team agreed on, so that what I build is what was asked for rather than what I noticed.
Requirements (2)
- dev01-ur1the story taken is named by the id the team's own list gives it, and by no id plumb made up
- dev01-nfr1plumb never decides what is on that list or its order
dev02 clarify what the story means Nothing holds it
As a developer holding a story I want its ambiguities settled before I write anything, so that I am not building my own reading of it.
Requirements (2)
- dev02-ur1an ambiguity is settled with whoever owns the story, before a test is written
- dev02-u1Amending a shared specification is not something one developer does alone, and nothing here says who agrees to it
dev03 open a session Proven
As a developer returning to work I want to be told where the last session stopped and whether the ground moved, so that I am not re-reading my own repository to work out what I was doing.
The tests that cite it (3)
tests/test_sessions.py::test_a_key_the_tool_does_not_know_rides_through_untouched— passed, ungroundedtests/test_sessions.py::test_where_the_cursor_lives_is_the_project_s_to_declare— passed, groundedtests/test_sessions.py::test_a_project_that_never_opens_a_session_keeps_every_capability— passed, grounded
Requirements (2)
- dev03-ur1opening and closing a session are optional, and no other step may come to depend on them
- dev03-sr1where the cursor lives and which trees a session spans are the project's own declaration
dev04 pull the working branch Nothing holds it
As a developer about to write code I want the branch current, so that what I prove is proven against what everybody else already has.
Requirements (1)
- dev04-ur1a story the branch's tests cite that the pull renamed or removed is reconciled before new tests are written against it
dev05 annotate and write the tests Unproven
As a developer I want the tests to exist before the code does, so that the work is aimed at something rather than described afterwards.
the citations that passed reached nothing wired — what ran was the implementation on its own, which is not evidence the story holds where it is used
The tests that cite it (1)
tests/test_board.py::test_the_only_authored_link_is_the_marker_on_the_test— passed, ungrounded
Requirements (4)
- dev05-ur1the annotation cites a story
- dev05-ur2the cited story exists
- dev05-ur3an annotated test shows derived status in the board even if the test body is empty
- dev05-ur4an annotation cites an id, and the id's namespace is what places it in one specification rather than another — which is how several specifications co-exist in one repository, how a typo'd id fails rather than landing beside a real one, and what a reader narrows a board by
dev06 do the work Nothing holds it
As a developer I want to build the thing the story asks for, so that the end-user gets their functionality.
Requirements (1)
- dev06-ur1the work is aimed at tests that already exist
dev06-1 say it in the reader's words Nothing holds it
As a developer I want a name for what the code holds that outlives the story's audience, so that the next audience to arrive does not rename the core.
Requirements (0)
dev07 run plumb Nothing holds it
As a developer who thinks the work is finished I want the tool to say whether it is proven, so that done informs my own judgement.
Requirements (2)
- dev07-ur1one command returns a board
- dev07-sr1the proving pipeline, which this step drills into
dev08 update the plumb configuration Unproven
As a developer whose proof came back at the wrong depth I want to correct what the tool was told, so that the answer is about my work rather than about my setup.
the citations that passed reached nothing wired — what ran was the implementation on its own, which is not evidence the story holds where it is used
The tests that cite it (5)
tests/test_adoption.py::test_the_plugin_stays_hashable_so_a_runner_may_hold_it_in_a_set— passed, ungroundedtests/test_artifact.py::test_a_project_declares_several_adapters_each_with_its_own_surface— passed, ungroundedtests/test_artifact.py::test_one_adapter_declared_the_ordinary_way_is_unchanged— passed, ungroundedtests/test_config.py::test_declaring_an_adapter_both_ways_is_refused_rather_than_resolved— passed, ungroundedtests/test_config.py::test_both_unambiguous_forms_still_work— passed, ungrounded
Requirements (2)
- dev08-ur1the board names what to correct
- dev08-nfr1an annotation alone is enough to begin; configuring is an enhancement
dev08-1 contribute a module Nothing holds it
As whoever builds a module I want to add a capability plumb lacks without forking it, so that a team that needs it installs it beside the tool it already has.
Requirements (0)
dev09 commit, naming the story Nothing holds it
As a developer whose work is proven I want the commit to name the story, so that the proof, the code and the claim travel together.
Requirements (3)
- dev09-ur1the commit names the story
- dev09-nfr1the commit follows the board rather than preceding it
- dev09-nfr2committing is frequent, so a working session is a sequence of proven steps
dev10 close the session Nothing holds it
As a developer returning to work I want the last session to have left a cursor and committed its work, so that it is easy to resume where I left off.
Requirements (1)
- dev10-ur1the session is measured as the change in what is proven, and by nothing else
dev11 push and open a pull request, naming the story Nothing holds it
As a developer who has finished I want the story named where the team will see it, so that its standing is read from what happened rather than typed by somebody.
Requirements (2)
- dev11-ur1the story id travels in the commit, the pull request and the merge
- dev11-nfr1integration with a team's story management tool is not part of plumb