git:20260723.1a09cde to git:20260729.0005d14

# Git Workflow Rules

## NEVER Push Directly to Main

**CRITICAL: Agents must NEVER push directly to the main branch.**

- Always work on a feature branch

- Commit and push to the feature branch only

- Let the user decide when to merge to main

- Do not merge to main without explicit user approval

```bash

# CORRECT workflow

git checkout -b feature/my-feature

# ... do work ...

git add .

git commit -m "My changes"

git push origin feature/my-feature

# STOP HERE - let user merge

# WRONG - never do this

git checkout main

git merge feature/my-feature

git push origin main # NO!

```

This ensures the user maintains control over what goes into the main branch.

## Changelog

Curate `[Unreleased]` in `CHANGELOG.md` as you land PRs. The root changelog is

the cross-package, user-facing release narrative for Relay. It follows

[Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and Semantic

Versioning.

An empty post-release changelog starts with `[Unreleased]`. The first pending

user-visible change must set the heading to `[Unreleased - Patch]`,

`[Unreleased - Minor]`, or `[Unreleased - Major]` according to its SemVer

impact. The pending release level is monotonic (`Patch < Minor < Major`):

raise the heading when a higher-impact change arrives; never lower it for a

later lower-impact change, and leave it unchanged for another change at the

same level. When a release is cut, move the pending entries under the released

version and restore an empty `[Unreleased]` heading with no release level.

Changelog entries should be concise and impact-first. Prefer one short bullet

per user-visible change: name the command, API, schema, or package touched and

the practical effect. Drop issue/PR links, internal review notes,

implementation backstory, release-only entries, and "foundation for..." phrasing

unless that text clearly explains the shipped impact.

Use Keep a Changelog sections (`Added`, `Changed`, `Deprecated`, `Removed`,

`Fixed`, `Security`), plus `Breaking Changes` and `Migration Guidance` when a

SemVer-major change needs explicit callouts. Do not use generated perspective

sections such as "Product Perspective", "Technical Perspective", or "Releases".

Do not add web-only changes to the changelog. Omit unpublished or withdrawn

versions as release headings; move their shipped user-visible changes into the

corrected published release.

Do not add `relay-feature-guardian` changes to the changelog. It is an internal

Slack feature-check agent (`.agentworkforce/agents/relay-feature-guardian/`),

not a user-facing Relay surface, so its fixes never belong in the release

narrative. The release workflow also skips these commits automatically.

## .trajectories Must Be Tracked

**CRITICAL: Never add `.agentworkforce/trajectories/` to `.gitignore`.**

The `.agentworkforce/trajectories/` directory must remain tracked in git. It contains trajectory records from the `trail` tool that provide valuable context for future agents and humans about past decisions, reasoning, and work history.

<!-- prpm:snippet:start @agent-workforce/trail-snippet@1.1.2 -->

# Trail

Record your work as a trajectory for future agents and humans to follow.

## Usage

If `trail` is installed globally, run commands directly:

```bash

trail start "Task description"

```

If not globally installed, use npx to run from local installation:

```bash

npx --yes agent-trajectories start "Task description"

```

## When Starting Work

Start a trajectory when beginning a task:

```bash

trail start "Implement user authentication"

```

With external task reference:

```bash

trail start "Fix login bug" --task "ENG-123"

```

## Recording Decisions

Record key decisions as you work:

```bash

trail decision "Chose JWT over sessions" \

--reasoning "Stateless scaling requirements"

```

For minor decisions, reasoning is optional:

```bash

trail decision "Used existing auth middleware"

```

**Record decisions when you:**

- Choose between alternatives

- Make architectural trade-offs

- Decide on an approach after investigation

## Recording Reflections

Periodically step back and synthesize progress:

```bash

trail reflect "Workers aligned on auth approach, API layer progressing well" \

--confidence 0.8

```

With focal points and adjustments:

```bash

trail reflect "Frontend and backend duplicating validation logic" \

--focal-points "duplication,ownership" \

--adjustments "Reassigning validation to backend team" \

--confidence 0.7

```

**Record reflections when you:**

- Have received several updates and need to synthesize the big picture

- Notice workers or tasks diverging from the plan

- Want to course-correct before continuing

- Are coordinating multiple agents and need to assess overall progress

Reflections differ from decisions: decisions record a specific choice,

reflections record a higher-level synthesis of what's happening and whether

the current approach is working.

## Completing Work

When done, complete with a retrospective:

```bash

trail complete --summary "Added JWT auth with refresh tokens" --confidence 0.85

```

After completing work, compact the finished trajectory or merged PR into a

durable summary. When the compacted summary is sufficient, discard the raw

source trajectories so `.trajectories/index.json` and list output stay focused:

```bash

trail compact --discard-sources

# or after a PR merge:

trail compact --pr 42 --discard-sources

```

`--discard-sources` removes the source trajectory JSON/Markdown/trace files and

updates the index. Use it after confirming the compacted artifact is the record

you want to keep.

**Confidence levels:**

- 0.9+ : High confidence, well-tested

- 0.7-0.9 : Good confidence, standard implementation

- 0.5-0.7 : Some uncertainty, edge cases possible

- <0.5 : Significant uncertainty, needs review

## Abandoning Work

If you need to stop without completing:

```bash

trail abandon --reason "Blocked by missing API credentials"

```

## Checking Status

View current trajectory:

```bash

trail status

```

## Listing and Viewing Trajectories

List all trajectories:

```bash

trail list

```

View a specific trajectory:

```bash

trail show <trajectory-id>

```

Export a trajectory (markdown, json, timeline, html):

```bash

trail export <trajectory-id> --format markdown

```

## Compacting Trajectories

After a PR merge, compact related trajectories into a single summary and prune

raw source trajectories when the summary should replace them:

```bash

trail compact --pr 42 --discard-sources

```

Compact by branch (finds trajectories with commits not in the specified base branch):

```bash

trail compact --branch main --discard-sources

```

Compact by specific commits:

```bash

trail compact --commits abc123,def456 --discard-sources

```

Compaction consolidates decisions and creates a grouped summary. Adding

`--discard-sources` makes the compacted artifact the durable record by removing

the raw trajectories and their index entries.

## Why Trail?

Your trajectory helps others understand:

- **What** you built (commits show this)

- **Why** you built it this way (trajectory shows this)

- **What alternatives** you considered

- **What challenges** you faced

Future agents can query past trajectories to learn from your decisions.

<!-- prpm:snippet:end @agent-workforce/trail-snippet@1.1.2 -->