📖 [Docs]: Contribution and PowerShell guidance made consistent (#75)

Contributors can follow the repository, agent setup, worktree,
issue-planning, and PowerShell example guidance without choosing between
contradictory instructions.

## Changed: Contribution guidance now agrees

- Repository standards use the canonical pull request body sequence:
summary, user-facing sections, optional technical details, then related
issues last.
- Worktree and root agent setup guidance keep concise local folder names
while using the required `<type>/<issue>-<slug>` branch names.
- Implementation plans organize tests alongside each behavior and
explicitly preserve test-first execution.
- PowerShell help guidance now identifies the generated
`psmodule.io/<Module>/Functions[/<Group>]/<Function>` URL used by
PSModule framework commands.

## Fixed: The FunctionCount skip example follows every remaining rule

Every displayed function now includes complete comment-based help,
matching `[OutputType()]` and `.OUTPUTS` metadata, typed and validated
parameters, implicit output, and a `.LINK` to the public function's
generated online reference page. Only the intentionally named
`FunctionCount` framework test is exempted.

## Technical Details

- Updated the canonical, agent, and example guidance identified by
#74 without changing unrelated content.
- Implementation plan progress: every task in #74 is
complete.
- Documentation index verification, link validation, and a clean
Zensical build are complete.

<details>
<summary>Related issues</summary>

- Fixes #74

</details>

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MariusStorhaug

AGENTS.md

@@ -11,7 +11,7 @@ If you find a problem, fix it if it's small; otherwise, register it as an issue
 2. Clone the ecosystem locally:
    1. <https://github.com/MSXOrg/docs> — requires PRs to be updated.
       - Clone as bare and use worktrees.
-      - Create a worktree for all branches - worktree = name of the branch.
+      - Create a worktree for every branch. Use a concise `<issue>-<slug>` worktree folder for a topic branch named `<type>/<issue>-<slug>`.
    2. <https://github.com/MSXOrg/memory/> — work directly towards main.
       - Simple clone, only main.
 

src/docs/Coding-Standards/PowerShell/Functions.md

@@ -115,6 +115,8 @@ Send each kind of message to the stream built for it, so a caller can capture, r
 
 Every function carries comment-based help — including internal and private helpers, not only the public surface. It is what lets a reader or an agent understand what the function does and how to call it without reading its body, and a private helper needs that as much as a public command does. Put it first inside the body, with sections in this order: `.SYNOPSIS` (one imperative sentence), `.DESCRIPTION`, at least one `.EXAMPLE` per behaviour, then `.INPUTS`, `.OUTPUTS` (matching `[OutputType()]`), `.NOTES`, `.LINK`. Document each parameter with an inline comment above it rather than a `.PARAMETER` block, and let comments explain *why*, not *what*.
 
+Functions in modules built with the PSModule framework use the generated online reference URL in `.LINK`: `https://psmodule.io/<ModuleName>/Functions/<Function-Name>` or, for a grouped command, `https://psmodule.io/<ModuleName>/Functions/<Group>/<Function-Name>`. A private helper links to the published public function it supports.
+
 ### `.INPUTS` and `.OUTPUTS`
 
 **`.INPUTS`** documents **pipeline input only** — types accepted via `ValueFromPipeline` or `ValueFromPipelineByPropertyName` parameters. It does not document ordinary parameters.

src/docs/Frameworks/Process-PSModule/skipping-framework-tests.md

@@ -58,38 +58,135 @@ Here's an example of a function file that skips the `FunctionCount` test because
 function Get-ComplexData {
     <#
         .SYNOPSIS
-        Retrieves complex data using helper functions.
+        Get formatted data from a file.
+
+        .DESCRIPTION
+        Read data from a file and format it as a structured object.
+
+        .EXAMPLE
+        Get-ComplexData -Path '.\data.txt'
+
+        Get the file content and its character count.
+
+        .INPUTS
+        None
+
+        You can't pipe objects to Get-ComplexData.
+
+        .OUTPUTS
+        System.Management.Automation.PSCustomObject
+
+        The formatted file data.
+
+        .NOTES
+        This file intentionally skips only the FunctionCount framework test.
+
+        .LINK
+        https://psmodule.io/<ModuleName>/Functions/Get-ComplexData
     #>
+    [OutputType([PSCustomObject])]
     [CmdletBinding()]
     param(
+        # The path to the data file.
         [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
         [string] $Path
     )
 
     $data = Get-RawData -Path $Path
-    $processed = Format-ComplexData -Data $data
-    return $processed
+    Format-ComplexData -Data $data
 }
 
 function Get-RawData {
+    <#
+        .SYNOPSIS
+        Get unformatted data from a file.
+
+        .DESCRIPTION
+        Read the complete content of a data file as one string.
+
+        .EXAMPLE
+        Get-RawData -Path '.\data.txt'
+
+        Get the complete content of the data file.
+
+        .INPUTS
+        None
+
+        You can't pipe objects to Get-RawData.
+
+        .OUTPUTS
+        System.String
+
+        The unformatted file content.
+
+        .NOTES
+        This function is a private helper for Get-ComplexData.
+
+        .LINK
+        https://psmodule.io/<ModuleName>/Functions/Get-ComplexData
+    #>
+    [OutputType([string])]
     [CmdletBinding()]
     param(
+        # The path to the data file.
         [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
         [string] $Path
     )
-    # Helper function implementation
+
+    Get-Content -LiteralPath $Path -Raw
 }
 
 function Format-ComplexData {
+    <#
+        .SYNOPSIS
+        Format raw data as a structured object.
+
+        .DESCRIPTION
+        Add useful metadata to raw data while preserving its content.
+
+        .EXAMPLE
+        Format-ComplexData -Data 'example'
+
+        Format the string and include its character count.
+
+        .INPUTS
+        None
+
+        You can't pipe objects to Format-ComplexData.
+
+        .OUTPUTS
+        System.Management.Automation.PSCustomObject
+
+        The formatted data and its character count.
+
+        .NOTES
+        This function is a private helper for Get-ComplexData.
+
+        .LINK
+        https://psmodule.io/<ModuleName>/Functions/Get-ComplexData
+    #>
+    [OutputType([PSCustomObject])]
     [CmdletBinding()]
     param(
+        # The raw content to format.
         [Parameter(Mandatory)]
-        $Data
+        [ValidateNotNullOrEmpty()]
+        [string] $Data
     )
-    # Helper function implementation
+
+    [PSCustomObject] @{
+        Content        = $Data
+        CharacterCount = $Data.Length
+    }
 }
 ```
 
+Replace `<ModuleName>` with the module's published name. If the public function belongs to a group, insert `<Group>/` between `Functions/` and `Get-ComplexData`.
+
+The skip exempts only `FunctionCount`. Every function in the file must still follow the [PowerShell function standard](../../Coding-Standards/PowerShell/Functions.md), including complete comment-based help, matching `[OutputType()]` and `.OUTPUTS` metadata, typed parameters, and implicit output.
+
 ## Best Practices
 
 - **Use skip comments sparingly**: Framework tests exist to maintain code quality and consistency. Only skip tests when absolutely necessary.

src/docs/Ways-of-Working/Git-Worktrees.md

@@ -35,14 +35,14 @@ In a single ordinary clone the opposite is forced: one branch checked out at a t
 ├── .bare/              # bare git data (the actual repository)
 ├── .git                # file containing: gitdir: ./.bare
 ├── <default>/          # worktree: default branch (always clean, never worked in directly)
-├── 42-add-pagination/  # worktree: issue #42 in progress
-└── 99-fix-null-ref/    # worktree: issue #99 in progress
+├── 42-add-pagination/  # worktree folder; branch: feat/42-add-pagination
+└── 99-null-ref/        # worktree folder; branch: fix/99-null-ref
 ```
 
 - **`.bare/`** — the shared git object store. All worktrees share this.
 - **`.git`** — a file (not a directory) that points git tooling to `.bare/`.
 - **`<default>/`** — the default branch worktree (e.g. `main` or `master`). Kept as a clean reference. Used for diffing, reading docs, running comparisons. Never directly committed to.
-- **`<N>-<slug>/`** — one worktree per issue in flight. Named by issue number and a short slug. Branch name matches the folder name.
+- **`<N>-<slug>/`** — one worktree folder per issue in flight, named by issue number and a short slug. The folder is a concise local path; its branch uses the required `<type>/<issue>-<slug>` name, so the two names do not need to match.
 
 ## Remotes
 
@@ -105,14 +105,16 @@ git -C .bare config "branch.$defaultBranch.merge" "refs/heads/$defaultBranch"
 ```powershell
 # From the repo root (where .bare/ lives)
 $defaultBranch = git -C .bare symbolic-ref HEAD | ForEach-Object { $_ -replace 'refs/heads/', '' }
-git -C .bare worktree add ../42-add-pagination -b 42-add-pagination $defaultBranch
+$worktreeName = '42-add-pagination'
+$branchName = 'feat/42-add-pagination'
+git -C .bare worktree add "../$worktreeName" -b $branchName $defaultBranch
 
 # Set upstream tracking (prevents "Publish Branch" prompt in VS Code)
-git -C .bare config branch.42-add-pagination.remote origin
-git -C .bare config branch.42-add-pagination.merge refs/heads/42-add-pagination
+git -C .bare config "branch.$branchName.remote" origin
+git -C .bare config "branch.$branchName.merge" "refs/heads/$branchName"
 
 # Open in VS Code
-code 42-add-pagination
+code $worktreeName
 ```
 
 Then follow the normal Implement flow: initial commit → push → draft PR → build → finalize.
@@ -124,7 +126,7 @@ Then follow the normal Implement flow: initial commit → push → draft PR →
 git -C .bare worktree remove 42-add-pagination
 
 # Delete the local branch ref
-git -C .bare branch -D 42-add-pagination
+git -C .bare branch -D feat/42-add-pagination
 
 # Prune if needed (removes stale worktree references)
 git -C .bare worktree prune

src/docs/Ways-of-Working/Issue-Format.md

@@ -229,10 +229,11 @@ The task-level roadmap. Implementers track progress here; reviewers use it to un
 Structure:
 
 - Every discrete piece of work is a checkbox: `- [ ]`.
-- Tasks are grouped under subheadings when work spans multiple areas (files, components, tests).
+- Tasks are grouped under subheadings when work spans multiple behaviors or dependencies. Keep each behavior's tests with its implementation tasks.
 - Each task is specific and actionable — file paths, function names, modules.
 - All tasks start unchecked. Checking happens during implementation.
-- Tasks are ordered logically — dependencies first, tests last.
+- Order groups and tasks so scope and dependencies are clear; the checklist layout is not a mandatory execution sequence.
+- Follow [test-first development](../Coding-Standards/Testing.md#test-first): define and run a behavior's test before implementing that behavior, regardless of how its checkboxes are organized.
 
 For PBIs and Epics, Section 3 is **a list of links to child issues**, not inline tasks. See [Issue Hierarchy](Issue-Hierarchy.md).
 
@@ -243,17 +244,17 @@ For PBIs and Epics, Section 3 is **a list of links to child issues**, not inline
 
 ## Implementation plan
 
-### Core changes
+### Paged responses
 
+- [ ] Add unit test for single-page response
+- [ ] Add unit test for multi-page response
 - [ ] Add a paged-request helper in `src/lib/`
 - [ ] Update the `repo list` command to call the paged variant in `src/commands/repository/`
-- [ ] Add a `--limit` option with integer type and validation
 
-### Tests
+### Result limiting
 
-- [ ] Add unit test for single-page response
-- [ ] Add unit test for multi-page response
 - [ ] Add unit test for `--limit` option limiting results
+- [ ] Add a `--limit` option with integer type and validation
 
 ### Documentation
 
@@ -375,17 +376,17 @@ multi-page, and `--limit` limiting.
 
 ## Implementation plan
 
-### Core changes
+### Paged responses
 
+- [ ] Add unit test for single-page response
+- [ ] Add unit test for multi-page response
 - [ ] Add a paged-request helper in `src/lib/`
 - [ ] Update the `repo list` command to call the paged variant in `src/commands/repository/`
-- [ ] Add a `--limit` option with integer type and validation
 
-### Tests
+### Result limiting
 
-- [ ] Add unit test for single-page response
-- [ ] Add unit test for multi-page response
 - [ ] Add unit test for `--limit` option limiting results
+- [ ] Add a `--limit` option with integer type and validation
 
 ### Documentation
 

src/docs/Ways-of-Working/Repository-Standard.md

@@ -110,7 +110,7 @@ Default title pattern:
 <Icon> [<Change type>]: <User-facing outcome>
 ```
 
-The description should lead with user-facing impact, then issue links when available, then user-facing change sections, with technical details at the bottom.
+The description should lead with user-facing impact, continue with user-facing change sections, include optional technical details after those sections, and end with the related-issues block.
 
 Repository templates may be simpler than the full PR Manager body, but they must gather enough information to reconstruct it.