Skip to content

Commit caffbe3

Browse files
MariusStorhaugMariusStorhaug
committed
Add comprehensive documentation for Agents, including principles, workflow, and standards
- Introduced Agents documentation with a focus on principles, workflow, and standards. - Created detailed sections on README-Driven Context, Review Etiquette, and GitHub Actions standards. - Established a clear structure for the Agents documentation, ensuring easy navigation and understanding. - Updated mkdocs.yml to include new Agents documentation in the navigation.
1 parent 510d954 commit caffbe3

14 files changed

Lines changed: 1421 additions & 0 deletions

‎docs/Agents/Commit-Conventions.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Commit Conventions
2+
3+
Commit messages serve two audiences: the engineer reading `git log` six months from now, and the agents trying to reconstruct what changed and why. Both need the same thing — **direct, descriptive messages** that say what was done.
4+
5+
## Rules
6+
7+
1. **State what was done or what the result is.** Imperative or declarative, both work.
8+
2. **No conventional-commit prefixes.** No `fix:`, `feat:`, `docs:`, `chore:`, `refactor:`, etc. The change type is captured at the PR level — repeating it on every commit adds noise without information.
9+
3. **No generic messages.** `Update for PR`, `WIP`, `fixes`, `more changes` — all forbidden. They erase traceability.
10+
4. **One logical change per commit.** Micro-iterative discipline. If a change touches three unrelated concerns, that's three commits.
11+
5. **Reference issues by number when natural** — but don't force it. `Fixes #N` belongs in the PR description, not every commit message.
12+
13+
## Examples
14+
15+
### Good
16+
17+
- `Add reserved word validation to Lua parser`
18+
- `Correct hex float parsing for negative exponents`
19+
- `Update installation prerequisites in README`
20+
- `Remove deprecated Get-Widget cmdlet`
21+
- `Switch pagination to link-header-based`
22+
- `Add regression test for null context in Resolve-GitHubContext`
23+
24+
### Bad
25+
26+
- `fix: parsing bug` — prefix + vague.
27+
- `Update for PR` — meaningless.
28+
- `WIP` — never commit work that needs a placeholder message; squash or amend first.
29+
- `Refactor stuff` — vague.
30+
- `Changes` — ø.
31+
32+
## Body (optional)
33+
34+
A commit message body is fine for non-trivial changes that need context. Keep it short. Wrap at ~72 characters per line.
35+
36+
```text
37+
Switch pagination to link-header-based
38+
39+
The previous page-number approach hardcoded the page size, which
40+
breaks when the API returns the default. Link headers are what
41+
the GitHub REST API documents as the supported pagination
42+
mechanism.
43+
```
44+
45+
## Why no conventional commits
46+
47+
PSModule classifies changes at the PR level via labels and the change-type field. The release note is generated from the PR description, not from commit messages. Conventional-commit prefixes inside the repo:
48+
49+
- Duplicate information already captured elsewhere.
50+
- Encourage `chore:` and `refactor:` over descriptive messages.
51+
- Lock the repo into a tooling pattern (Commitizen, semantic-release) that PSModule doesn't use.
52+
53+
Direct, descriptive messages serve both engineers and agents without the ceremony.
54+
55+
## When working with agents
56+
57+
The Builder writes commits during the micro-iterative loop. Each commit covers one discrete change. The Responder writes commits when addressing review feedback — one commit per thread when practical, so the link between feedback and fix is preserved in history.
58+
59+
Never let an agent commit with a placeholder message. If a commit can't be described in one clear line, the change is probably too broad — split it.

‎docs/Agents/Issue-Format.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# Issue Format
2+
3+
Every issue in the PSModule organization follows the same structure. The format makes issues:
4+
5+
- **Readable** by anyone — human or agent — without prior context.
6+
- **Actionable** by an implementer without back-and-forth.
7+
- **Traceable** because decisions and changes are recorded.
8+
9+
## Properties of every issue
10+
11+
- **Every change has an issue.** Features, fixes, refactors, documentation, maintenance — all tracked as issues before work begins.
12+
- **The description is the single source of truth.** It reflects the current state of the work at all times. Decisions, scope changes, and approach changes are written directly into the description.
13+
- **Comments record change history only.** Each description update is accompanied by a comment summarizing what changed and why.
14+
- **Tone is impersonal.** No first-person ("I", "my") or second-person ("you", "your") language. Neutral references like "the user", "the developer", or passive constructions.
15+
- **External references are hyperlinks.** Every mention of an API, RFC, library, doc, or tool is a clickable `[text](url)` link. No bare URLs.
16+
- **No duplicates.** Existing issues are searched before creating or restructuring. Duplicates are consolidated or cross-linked.
17+
18+
## Title
19+
20+
A clear, imperative-mood statement of the work. Not a question, not a symptom.
21+
22+
- Scope or area when it aids disambiguation: `Build-PSModule: Add retry logic to publish step`.
23+
- No type prefixes (`[Bug]`, `[Feature]`) — labels handle categorization.
24+
25+
### Well-formed
26+
27+
- `Add pagination support to Get-GitHubRepository`
28+
- `Fix null reference when Context is not resolved`
29+
- `Update installation guide with prerequisites`
30+
31+
### Malformed
32+
33+
- `Bug in module`
34+
- `Please fix`
35+
- `WIP`
36+
37+
## The three sections
38+
39+
The description has three sections separated by horizontal rules (`---`), ordered from behavioural to architectural to tactical. The user need is understood before the technical discussion.
40+
41+
| Section | Owner | Present in |
42+
| ------- | -------------- | ----------------------------------------------------- |
43+
| 1 — Context and Request | Ideator → Clarifier | Every issue at every level (Task, PBI, Epic) |
44+
| 2 — Technical Decisions | Planner | Task always; PBI / Epic for decomposition rationale |
45+
| 3 — Implementation Plan | Planner | Task always (task list); PBI / Epic (links to children) |
46+
47+
## Section 1 — Context and Request
48+
49+
Describes the **user experience** — what someone wants, what isn't working, or what is missing. Written from the user's perspective, not the implementer's.
50+
51+
Two parts:
52+
53+
- **Context** — who the user is, what they're trying to accomplish, the situation.
54+
- **Request** — the problem or need, as the user experiences it.
55+
56+
Answers:
57+
58+
- What does the user want to do?
59+
- What is the user experiencing today (for bugs / gaps)?
60+
- What should the experience look like instead?
61+
- Why does it matter?
62+
63+
Framing by work type:
64+
65+
| Type | Framing |
66+
| -------------- | ---------------------------------------------------------------------- |
67+
| Feature | Desired capability from the user's point of view. |
68+
| Bug / Fix | What happens vs. What is expected. |
69+
| Change request | Current experience vs. Desired experience. |
70+
| Maintenance | User impact — how internal work improves reliability, speed, etc. |
71+
| Documentation | What is confusing or missing — the gap a user runs into. |
72+
73+
Elements per work type:
74+
75+
| Element | Feature | Bug / Fix | Change request | Maintenance | Documentation |
76+
| ------------------------ | :-----: | :-------: | :------------: | :---------: | :-----------: |
77+
| Acceptance criteria | ✓ | ✓ | ✓ | ✓ | ✓ |
78+
| Reproduction steps | | ✓ | | | |
79+
| Environment / version | | ✓ | | | |
80+
| Regression indicator | | ✓ | | | |
81+
| Known workarounds | | ✓ | ○ | | |
82+
| Error messages / logs | | ✓ | | ○ | |
83+
| Screenshots / visuals | ○ | ✓ | ○ | | ○ |
84+
85+
✓ = present when applicable, ○ = optional
86+
87+
This section **does not contain** file paths, function internals, API endpoints, or implementation patterns. Those belong in Section 2.
88+
89+
## Section 2 — Technical Decisions
90+
91+
The technical choices that shape the plan. Sits between the user-facing request and the tactical plan.
92+
93+
Why this section exists:
94+
95+
- Different technical choices lead to fundamentally different plans — deciding upfront avoids rework.
96+
- Conscious, documented choices replace implicit assumptions buried in code.
97+
- Reviewers see the **reasoning** behind the plan, not just the plan itself.
98+
99+
Structure:
100+
101+
- Each decision is a bolded label or heading, followed by the chosen approach and a brief rationale.
102+
- Alternatives considered are included when they help explain the choice.
103+
- Open decisions are marked with `Open:` and resolved before the implementation plan is written.
104+
- When a decision changes later, this section is updated and a comment documents the change.
105+
106+
Typical decision areas:
107+
108+
- Where new code lives (paths, modules).
109+
- Patterns or conventions followed (e.g., "follow the existing pattern in `Get-GitHubRelease`").
110+
- Naming choices.
111+
- Whether to extend or create new.
112+
- Dependencies on other functions, modules, or APIs.
113+
- Error handling strategy.
114+
- Breaking changes and backward compatibility.
115+
- Test strategy (unit, integration, mocks).
116+
117+
## Section 3 — Implementation Plan
118+
119+
The task-level roadmap. Implementers track progress here; reviewers use it to understand scope.
120+
121+
Structure:
122+
123+
- Every discrete piece of work is a checkbox: `- [ ]`.
124+
- Tasks are grouped under subheadings when work spans multiple areas (files, components, tests).
125+
- Each task is specific and actionable — file paths, function names, modules.
126+
- All tasks start unchecked. Checking happens during implementation.
127+
- Tasks are ordered logically — dependencies first, tests last.
128+
129+
For PBIs and Epics, Section 3 is **a list of links to child issues**, not inline tasks. See [Issue Hierarchy](Issue-Hierarchy.md).
130+
131+
## Comments
132+
133+
Every description update is accompanied by a comment. Comments preserve the change history so reasoning is not lost when the description is overwritten.
134+
135+
A comment contains:
136+
137+
- A brief summary line.
138+
- Bullet points detailing what was added, changed, or removed.
139+
- Any gaps or open questions that need input.
140+
141+
## Formatting
142+
143+
Issues use [GitHub Flavored Markdown](https://github.github.com/gfm/) with the full feature set:
144+
145+
- `- [ ]` / `- [x]` task lists.
146+
- Tables for comparisons, label definitions, decision matrices.
147+
- Fenced code blocks with language identifiers.
148+
- `>` blockquotes for callouts.
149+
- `> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]` alerts.
150+
- `<details><summary>…</summary>…</details>` collapsible sections.
151+
- `#123`, `@user`, and commit SHA autolinks.
152+
- Backtick-wrapped inline code for identifiers.
153+
- `---` horizontal rules between sections.
154+
- `[text](url)` links for all external references.
155+
- **No hard line breaks within a paragraph.** GitHub renders mid-paragraph newlines as spaces, which creates inconsistent visual spacing.
156+
157+
## Labels
158+
159+
Labels categorize. The category is never encoded in the title.
160+
161+
| Label | Use for |
162+
| ----------- | ---------------------------------------------------- |
163+
| `Major` | Breaking changes |
164+
| `Minor` | New features or enhancements |
165+
| `Patch` | Small fixes or improvements |
166+
| `NoRelease` | Documentation, maintenance, CI/CD — no version bump |
167+
| `Bug` | Bug reports |
168+
| `Feature` | Feature requests |
169+
| `Question` | Questions or discussion |
170+
171+
Issue **types** (Epic / PBI / Task) are GitHub-native and separate from labels — see [Issue Hierarchy](Issue-Hierarchy.md).

‎docs/Agents/Issue-Hierarchy.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Issue Hierarchy
2+
3+
Work in PSModule is tracked at three levels. The level reflects **scope and aggregation**, not priority or complexity. We use **GitHub issue types** for the segmentation — not labels — so the relationships are first-class in the platform.
4+
5+
## The three levels
6+
7+
| Level | Issue type | Scope | Output |
8+
| ------------------------ | ------------ | -------------------------------------------------- | --------------------------------------------------------- |
9+
| **Task** | `Task` | One deliverable. One small reviewable PR. | Working software. |
10+
| **Product Backlog Item** | `PBI` | A body of work composed of multiple Tasks. | Tracking, delegation, oversight, visibility into progress. |
11+
| **Epic** | `Epic` | Strategic chunk needing multiple PBIs. | The co-planning artifact. Where OKRs become initiatives. |
12+
13+
> The name **Product Backlog Item** is chosen for its neutral vibe — it works equally well for a feature, a fix, a refactor, or an internal capability. "Feature" implies user-visible value, which isn't always the case for the middle tier.
14+
15+
## When to use each level
16+
17+
### Task
18+
19+
Use Task when:
20+
21+
- The work has one clear deliverable.
22+
- The expected PR is small and reviewable in a single pass (rough guideline: under ~500 lines / 15 files).
23+
- One person (or one agent) can pick it up and finish it independently.
24+
25+
A Task is the **default starting point**. Promote upward only when you discover the work is too big.
26+
27+
### Product Backlog Item
28+
29+
Use PBI when:
30+
31+
- The work has multiple distinct deliverables, each of which would be its own PR.
32+
- The deliverables share a goal but can be sequenced or parallelized.
33+
- You want oversight over the body of work without prescribing the order.
34+
35+
A PBI's children can themselves be PBIs (nested decomposition) when the inner deliverables also break into multiple chunks. Epic → PBI → PBI → Task is legitimate when the work demands it.
36+
37+
### Epic
38+
39+
Use Epic when:
40+
41+
- The work spans multiple PBIs.
42+
- It maps to a strategic objective — an OKR, an initiative, an organizational goal.
43+
- Multiple teams or contributors should co-plan around it.
44+
45+
> "As a business we want to deliver this. What do we collectively need to do?"
46+
47+
That conversation lives on an Epic.
48+
49+
## Nested decomposition
50+
51+
Nesting is fine and expected:
52+
53+
```text
54+
Epic (initiative, ties to an OKR)
55+
├── PBI (one body of work)
56+
│ ├── Task (one PR)
57+
│ ├── Task
58+
│ └── PBI (further breakdown when needed)
59+
│ ├── Task
60+
│ └── Task
61+
└── PBI
62+
└── Task
63+
```
64+
65+
The rule: **one Task = one PR-sized deliverable**. Everything above is for aggregation.
66+
67+
## How to express the hierarchy
68+
69+
Use GitHub's **sub-issue relationship** between issue types. This is a first-class GitHub feature — not just text references — and the [Planner](https://github.com/PSModule/.github-private/blob/main/agents/planner.md) agent creates these relationships when decomposing.
70+
71+
Text-level conventions on child issues:
72+
73+
- `Parent: #N` at the top of Section 1 (a courtesy duplicate of the GitHub link).
74+
- `Blocked by: #M` when sequencing matters.
75+
- Acceptance criteria scoped to **just this child's slice**, not the parent's whole goal.
76+
77+
## How the sections differ by level
78+
79+
| Section | Task | PBI | Epic |
80+
| ------------------------ | ----------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------- |
81+
| Section 1 (Context/Req) | The deliverable's user story | The grouped goal's user story | The strategic outcome — vision, why, the change in the world |
82+
| Section 2 (Decisions) | Implementation decisions | Decomposition rationale + interface decisions between children | Decomposition rationale + which PBIs and why |
83+
| Section 3 (Plan) | Checkbox task list | Linked list of child issues (Tasks and/or sub-PBIs) | Linked list of child PBIs |
84+
85+
For Epics, Section 1 should explicitly contain the **Golden Circle framing**: Why, How, What. See [Principles → Golden Circle](Principles.md#start-with-why--the-golden-circle).
86+
87+
## Why three levels and not more
88+
89+
Three is enough to:
90+
91+
- Cover **strategic** (Epic), **tactical** (PBI), and **operational** (Task) horizons.
92+
- Match how teams co-plan in larger frameworks (SAFe, Nexus) without inheriting their ceremony.
93+
- Aggregate progress meaningfully — an Epic burns down as its PBIs complete; a PBI burns down as its Tasks complete.
94+
95+
More levels create overhead. Fewer levels lose the ability to track progress across bodies of work.
96+
97+
## Promotion and demotion
98+
99+
A Task can be **promoted** to a PBI when it turns out to be bigger than expected. The Planner does this — Section 2 records the discovery, and the inline task list becomes child issues.
100+
101+
A PBI can be **demoted** to a Task when decomposition reveals only one real deliverable. Close the would-be-children, fold their content into the Task's Section 3.
102+
103+
Promotion / demotion always leaves a comment audit trail explaining the change.

0 commit comments

Comments
 (0)