Skip to content

Commit e25dc16

Browse files
MariusStorhaugMariusStorhaug
committed
Add Workflow to Ways of Working and refactor Agents references
Move the canonical workflow description (phases: Capture, Refine, Plan, Build, Review, Ship, Operate) into Ways-of-Working/Workflow.md as the central document for how work happens. The Agents/Workflow.md is slimmed to map agent roles onto those phases, referencing the shared document. Removes CDLC/SDLC jargon from Principles.md in favour of plain-language descriptions (Context maintenance / Software delivery). Ways-of-Working/index.md now lists Workflow as the first entry.
1 parent 3369c56 commit e25dc16

5 files changed

Lines changed: 182 additions & 64 deletions

File tree

‎docs/Agents/Workflow.md‎

Lines changed: 10 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,22 @@
11
# Workflow
22

3-
How the agent roles connect across the **Context Development Lifecycle (CDLC)** and the **Software Development Lifecycle (SDLC)**, embedded in DevOps practice.
3+
How the agent roles map to the [Ways of Working workflow](../Ways-of-Working/Workflow.md). Each phase is owned by a specific agent.
44

5-
## The big picture
6-
7-
The CDLC and the SDLC run side by side. The CDLC keeps **context** evergreen — issues, decisions, READMEs, docs. The SDLC delivers **software** — code, tests, releases. Each iteration of one feeds the other.
5+
## The lifecycle
86

97
```text
10-
┌───────────────────────────────────────────────────────┐
11-
│ Context Development Lifecycle │
12-
│ │
13-
│ Define │
14-
│ (capture → refine → plan) │
15-
│ │ │
16-
│ ┌──────────────┼──────────────┐ │
17-
│ ▼ ▼ ▼ │
18-
│ simple task sub-issues checklist │
19-
│ │
20-
└───────────────────────┼───────────────────────────────┘
21-
│
22-
▼
23-
┌───────────────────────┼───────────────────────────────┐
24-
│ │ │
25-
│ Software Development Lifecycle │
26-
│ │
27-
│ Implement │
28-
│ (branch → draft PR → build → finalize) │
29-
│ │ │
30-
│ ▼ │
31-
│ Reviewer │
32-
│ │ │
33-
│ fixes needed? → Implement (respond) │
34-
│ │
35-
└───────────────────────────────────────────────────────┘
36-
│
37-
▼
38-
Run / operate
39-
(DevOps + SRE loop)
40-
│
41-
▼
42-
Signals, errors, feedback
43-
│
44-
▼
45-
Define (again)
8+
Define → Implement → Reviewer
9+
↑ │
10+
└── (respond) ◄┘
4611
```
4712

13+
Each role is a focused agent. The shared workflow and conventions are documented in [Ways of Working](../Ways-of-Working/index.md) — agents read those pages as context before acting.
14+
4815
## The agents
4916

5017
### Define
5118

52-
Combines **capture**, **refine**, and **plan** into a single flow. Takes any input — a desire, a bug, a signal — and produces a planned, actionable issue.
19+
Covers the **Capture**, **Refine**, and **Plan** phases. Takes any input — a desire, a bug, a signal — and produces a planned, actionable issue.
5320

5421
**Output is one of:**
5522

@@ -60,7 +27,7 @@ See [Issue Format](../Ways-of-Working/Issue-Format.md) and [Issue Hierarchy](../
6027

6128
### Implement
6229

63-
Takes a planned issue and delivers a merge-ready pull request. Owns the full loop:
30+
Covers the **Build** and **Ship** phases. Takes a planned issue and delivers a merge-ready pull request. Owns the full loop:
6431

6532
1. **Orient** — read the issue, README, contribution guide, and standards.
6633
2. **Branch and draft PR** — create a [worktree](Git-Worktrees.md) for the issue, push early so CI attaches and progress is visible. Assign to the user. Link to the issue.
@@ -72,24 +39,10 @@ See [Git Worktrees](Git-Worktrees.md), [PR Format](../Ways-of-Working/PR-Format.
7239

7340
### Reviewer
7441

75-
Reviews someone else's PR. Checks delivery against the linked issue, good taste, security, and undiscussed decisions.
42+
Covers the **Review** phase. Reviews someone else's PR. Checks delivery against the linked issue, good taste, security, and undiscussed decisions.
7643

7744
See [Review Etiquette](../Ways-of-Working/Review-Etiquette.md).
7845

79-
## Three horizons of planning
80-
81-
Borrowed from [Principles → Roadmapping](../Ways-of-Working/Principles.md#roadmapping). The planner doesn't only think about today.
82-
83-
| | Now | Next | Later |
84-
| ---------- | -------------------- | ------------- | -------------- |
85-
| Conceptual | Vision delivered now | Vision next | Vision later |
86-
| Logical | Approach now | Approach next | Approach later |
87-
| Detailed | Tasks in flight | Tasks ready | Tasks framed |
88-
89-
- A Task lives in **Now / Detailed**.
90-
- A PBI lives somewhere between **Now / Logical** and **Next / Detailed**.
91-
- An Epic spans **Now → Next → Later** at **Conceptual / Logical** fidelity.
92-
9346
## Where the principles show up
9447

9548
| Principle | Most relevant agent |

‎docs/Agents/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,14 +20,14 @@ Principles, issue format, PR format, commit conventions, review etiquette, and o
2020

2121
## The lifecycle
2222

23+
The full workflow — phases, the loop, and how they connect — is documented in **[Ways of Working → Workflow](../Ways-of-Working/Workflow.md)**. The agents implement that workflow:
24+
2325
```text
2426
Define → Implement → Reviewer
2527
↑ │
2628
└── (respond) ◄┘
2729
```
2830

29-
Each role is a focused agent. Standards are referenced, not embedded.
30-
3131
| Role | Phase | Purpose |
3232
| ----------- | ----------------------- | ----------------------------------------------------------------------- |
3333
| Define | Capture + Refine + Plan | Capture a desire, ground it, and produce a planned issue or sub-issues. |

‎docs/Ways-of-Working/Principles.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -165,14 +165,16 @@ Define the tests when you define the behavior. Update them when behavior changes
165165
166166
Everything is continuous — development, integration, delivery, operation. The same team owns the system across the loop. Build the systems, the practices, and the teams that internalize this.
167167

168-
## Context Development Lifecycle
168+
## Context as a product
169169

170-
The work of keeping context **right, evergreen, and declarative**. The CDLC sits beside the SDLC:
170+
The work of keeping context **right, evergreen, and declarative** runs alongside software delivery:
171171

172-
- **SDLC** delivers software using source code management, CI/CD, and DevOps practices.
173-
- **CDLC** delivers context — issues, decisions, READMEs, agent definitions, this docs site — and treats them as products that must be kept current.
172+
- **Software delivery** produces code, tests, and releases using source control, CI/CD, and DevOps practices.
173+
- **Context maintenance** produces issues, decisions, READMEs, agent definitions, and documentation — and treats them as products that must be kept current.
174174

175-
Both lifecycles run continuously. Each iteration of the SDLC produces context that needs CDLC maintenance; each iteration of the CDLC unblocks SDLC work.
175+
Both run continuously. Each iteration of software delivery produces context that needs maintenance; each iteration of context maintenance unblocks the next round of software work.
176+
177+
See [Workflow](Workflow.md) for how these connect in practice.
176178

177179
## Lean Software Development
178180

‎docs/Ways-of-Working/Workflow.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Workflow
2+
3+
How work flows from idea to delivery — and back again. This is the heartbeat of the PSModule ecosystem.
4+
5+
## The big picture
6+
7+
Two things run side by side, continuously:
8+
9+
1. **Context** — keeping issues, decisions, READMEs, and documentation right and evergreen.
10+
2. **Software** — delivering code, tests, and releases.
11+
12+
Each feeds the other. Software produces signals that require context maintenance. Refined context unblocks the next round of software work. The loop never stops.
13+
14+
```text
15+
┌───────────────────────────────────────────────────────┐
16+
│ Context maintenance │
17+
│ │
18+
│ Capture → Refine → Plan │
19+
│ │ │
20+
│ ┌──────────────┼──────────────┐ │
21+
│ ▼ ▼ ▼ │
22+
│ simple task sub-issues checklist │
23+
│ │
24+
└───────────────────────┼───────────────────────────────┘
25+
│
26+
▼
27+
┌───────────────────────┼───────────────────────────────┐
28+
│ │ │
29+
│ Software delivery │
30+
│ │
31+
│ Branch → Draft PR → Build → Finalize │
32+
│ │ │
33+
│ ▼ │
34+
│ Review │
35+
│ │ │
36+
│ fixes needed? → respond │
37+
│ │
38+
└───────────────────────────────────────────────────────┘
39+
│
40+
▼
41+
Run and operate
42+
(DevOps + SRE loop)
43+
│
44+
▼
45+
Signals, errors, feedback
46+
│
47+
▼
48+
Capture (again)
49+
```
50+
51+
## Phases
52+
53+
### Capture
54+
55+
A desire for change enters the system. It can come from anywhere:
56+
57+
- A user request or feature idea.
58+
- A bug report or error signal.
59+
- An observation during a review.
60+
- A dependency update or platform change.
61+
62+
The goal is to **write it down** — quickly, in a GitHub issue — so it exists outside someone's head. At this stage, precision is less important than existence. The issue captures the current state, the pain or opportunity, and the desired outcome.
63+
64+
See [Issue Format § Section 1](Issue-Format.md) for structure.
65+
66+
### Refine
67+
68+
Ground the captured desire in reality. Ask:
69+
70+
- What is the actual problem? (Not the symptom, not the first solution that comes to mind.)
71+
- Who is affected and how?
72+
- What does "done" look like from the user's perspective?
73+
- Are there constraints, dependencies, or prior decisions that matter?
74+
75+
This may involve questions in issue comments, interactive discussion, or research. The goal is **shared understanding** — everyone (humans and agents) agrees on what the real problem is and what the outcome should be.
76+
77+
### Plan
78+
79+
Turn the refined understanding into actionable work:
80+
81+
- **Decisions** — what approach will we take? What trade-offs are we making? Document them in the issue.
82+
- **Decomposition** — if the work is large, break it into sub-issues. Each sub-issue should be deliverable in a single pull request.
83+
- **Checklist** — for a single task, list the concrete steps in the issue body.
84+
85+
The plan is the contract. It drives implementation.
86+
87+
See [Issue Format § Sections 2–3](Issue-Format.md), [Issue Hierarchy](Issue-Hierarchy.md).
88+
89+
### Build
90+
91+
Execute the plan:
92+
93+
1. **Branch** — create a branch (and [worktree](../Agents/Git-Worktrees.md)) for the issue.
94+
2. **Draft PR** — push early and open a draft pull request. Link it to the issue. This makes progress visible and attaches CI from the start.
95+
3. **Implement** — work through the checklist. One logical change per commit. Update the issue as each task completes.
96+
4. **Test locally** — don't push known failures to CI. Push work as far inward as it can go.
97+
98+
See [Commit Conventions](Commit-Conventions.md), [PR Format](PR-Format.md).
99+
100+
### Review
101+
102+
Every change gets a second perspective:
103+
104+
- Does the PR deliver what the linked issue asks for?
105+
- Does it follow the project's standards and conventions?
106+
- Are there security concerns or undiscussed decisions?
107+
- Is the code clear and maintainable?
108+
109+
Feedback is processed one thread at a time: read → evaluate → fix → reply → resolve.
110+
111+
See [Review Etiquette](Review-Etiquette.md).
112+
113+
### Ship
114+
115+
When all tasks are complete, CI is green, and review is approved:
116+
117+
1. Update the PR title and description as a user-facing release note.
118+
2. Apply the correct labels (Major, Minor, Patch, etc.).
119+
3. Mark ready for review (or merge, depending on the project's flow).
120+
121+
The PR description becomes the release note. Write it for end users, not reviewers.
122+
123+
See [PR Format](PR-Format.md).
124+
125+
### Operate
126+
127+
> You build it, you run it.
128+
129+
After merge, the system is live. Monitor, observe, respond to signals. When something breaks or an opportunity appears — the loop starts again at **Capture**.
130+
131+
## Three horizons of planning
132+
133+
Planning happens at different time horizons and levels of detail:
134+
135+
| | Now | Next | Later |
136+
| ---------- | -------------------- | ------------- | -------------- |
137+
| Conceptual | Vision delivered now | Vision next | Vision later |
138+
| Logical | Approach now | Approach next | Approach later |
139+
| Detailed | Tasks in flight | Tasks ready | Tasks framed |
140+
141+
- **Now / Next / Later** are time horizons without firm dates.
142+
- **Conceptual / Logical / Detailed** are levels of fidelity.
143+
144+
Detail increases as work moves from Later toward Now.
145+
146+
- A single task lives in **Now / Detailed**.
147+
- A product backlog item lives between **Now / Logical** and **Next / Detailed**.
148+
- An epic spans **Now → Next → Later** at **Conceptual / Logical** fidelity.
149+
150+
## Guiding principles in the workflow
151+
152+
| Principle | Where it shows up |
153+
| -------------------------------- | ---------------------------------------- |
154+
| Start with Why (Golden Circle) | Capture and Refine — grounding the work |
155+
| OKRs | Capture (especially at Epic level) |
156+
| YAGNI / Lean | Plan and Build — thinnest viable path |
157+
| Test-Driven Development | Build — define tests with behavior |
158+
| DevOps / SRE | Operate — continuous loop |
159+
| 4-eyes principle | Review — every change gets a second look |
160+
| Everything as Code | All phases — issues, PRs, docs in source |
161+
162+
See [Principles](Principles.md) for the full set.

‎docs/Ways-of-Working/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ This section documents the principles, processes, and norms that every contribut
66

77
## What's covered
88

9+
- **[Workflow](Workflow.md)** — How work flows from idea to delivery and back again. The phases, the loop, and how they connect.
910
- **[Principles](Principles.md)** — Vision, mission, OKRs, product mindset, and the foundational beliefs that drive decisions.
1011
- **[Issue Format](Issue-Format.md)** — The three-section issue structure, formatting rules, and labels.
1112
- **[Issue Hierarchy](Issue-Hierarchy.md)** — Epic / Product Backlog Item / Task levels and GitHub issue types.

0 commit comments

Comments
 (0)